{"id":237,"date":"2024-04-07T08:00:00","date_gmt":"2024-04-07T12:00:00","guid":{"rendered":"https:\/\/gerardomiranda.dev\/blog\/?p=237"},"modified":"2024-04-07T12:44:32","modified_gmt":"2024-04-07T16:44:32","slug":"unlocking-the-potential-of-ruby-on-rails-custom-generators","status":"publish","type":"post","link":"https:\/\/gerardomiranda.dev\/blog\/unlocking-the-potential-of-ruby-on-rails-custom-generators\/","title":{"rendered":"Unlocking the potential of Ruby on Rails custom generators"},"content":{"rendered":"\n

In the last weeks I have been using mason <\/a>to generate some boiler plate code for my personal project, may have to write about it some other time. So the idea of templating was sitting in my head at all times.<\/p>\n\n\n\n

Then at my job I got assigned a task, a very common task actually, a third party integration. So my first thought was, I can use mason to generate some templates and make all our data processors consistent. Very excited, I went to ask for permission to create a new repository where I was already imagining filling it up with bricks (bricks are templates that mason uses to create your code). But the lead dev asked “doesn’t Rails have a feature for that?”.<\/p>\n\n\n\n

At first I was thinking, “oh no! they don’t get it”. But after the initial reaction, it actually sound like a pretty good idea, so I went on to investigate about Rails generators, to see if we could use them for this case. The official docs didn’t have a very complete example, so I started looking for some blog posts and the API reference as well. I didn’t find any comprehensive guide, so I went on to experiment with it, I can show you a bit of the work I accomplished with it (not the real thing obviously) in case you need a more concrete example of how to create Rails generators.<\/p>\n\n\n\n

Preparing<\/h2>\n\n\n\n

First let’s build something simple, like a service for getting animal pictures, there we are going to have options to show pictures from different kinds of animals.<\/p>\n\n\n

rails g controller AnimalPictures index<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
Since cats are my favorite animals we will start with pictures of cats, lets add an image_tag and a button to retrieve the cat picture. Don’t forget to add the route for our post method get_cat, and in the controller we are going to retrieve a cute cat image I found with google.<\/p>\n\n\n\n
animal_pictures\/index.html.erb<\/strong><\/p>\n\n\n
<h1<\/span>><\/span>AnimalPictures#index<\/h1<\/span>><\/span><\/span>\n<\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span><%<\/span><\/span><\/span> unless<\/span> @image_url.nil<\/span>? <\/span>%><\/span><\/span><\/span><\/span>\n<\/span><\/span>    <%=<\/span><\/span><\/span> image_tag @image_url, size:<\/span>\"512x512\"<\/span> <\/span>%><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span><%<\/span><\/span><\/span> end<\/span><\/span>%><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span><%=<\/span><\/span><\/span> button_to \"Cats\"<\/span>, action:<\/span> :get_cat<\/span> <\/span>%><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span><\/span>\n<\/span><\/span><\/code><\/span>Code language:<\/span> ERB (Embedded Ruby)<\/span> (<\/span>erb<\/span>)<\/span><\/small><\/pre>\n\n\n
config\/routes.rb<\/strong><\/p>\n\n\n
get 'animal_pictures\/index'<\/span>\npost 'animal_pictures\/get_cat'<\/span><\/code><\/span>Code language:<\/span> Ruby<\/span> (<\/span>ruby<\/span>)<\/span><\/small><\/pre>\n\n\n
animal_pictures_controller.rb<\/strong><\/p>\n\n\n
class<\/span> AnimalPicturesController<\/span> < ApplicationController<\/span>\n<\/span><\/span>  def<\/span> index<\/span><\/span>\n<\/span><\/span>    @image_url = params[:image_url<\/span>]\n<\/span><\/span>  end<\/span>\n<\/span><\/span>\n<\/span><\/span>  def<\/span> get_cat<\/span><\/span>\n<\/span><\/span>    redirect_to action:<\/span> :index<\/span>, image_url:<\/span> 'https:\/\/i.natgeofe.com\/n\/548467d8-c5f1-4551-9f58-6817a8d2c45e\/NationalGeographic_2572187_square.jpg'<\/span>\n<\/span><\/span>  end<\/span>\n<\/span><\/span>end<\/span>\n<\/span><\/span><\/code><\/span>Code language:<\/span> Ruby<\/span> (<\/span>ruby<\/span>)<\/span><\/small><\/pre>\n\n\n
app\/services\/cats\/client.rb<\/strong><\/p>\n\n\n
module<\/span> Cats<\/span><\/span>\n<\/span><\/span>\n<\/span><\/span>  class<\/span> Client<\/span><\/span>\n<\/span><\/span>    include<\/span> HTTParty\n<\/span><\/span>\n<\/span><\/span>    base_uri 'https:\/\/api.thecatapi.com'<\/span>\n<\/span><\/span>\n<\/span><\/span>    def<\/span> initialize<\/span><\/span>\n<\/span><\/span>    end<\/span>\n<\/span><\/span>\n<\/span><\/span>    def<\/span> get_picture_url<\/span><\/span>\n<\/span><\/span>      response = self<\/span>.class<\/span>.get<\/span>('\/v1<\/span>\/images<\/span>\/search<\/span>')<\/span>\n<\/span><\/span>      response.parsed_response[0<\/span>]['url'<\/span>]\n<\/span><\/span>    end<\/span>\n<\/span><\/span>\n<\/span><\/span>  end<\/span>\n<\/span><\/span>end<\/span>\n<\/span><\/span><\/code><\/span>Code language:<\/span> Ruby<\/span> (<\/span>ruby<\/span>)<\/span><\/small><\/pre>\n\n\n
And now we modify our get_cat method to use this API<\/p>\n\n\n\n
animal_pictures_controller.rb<\/strong><\/p>\n\n\n
def<\/span> get_cat<\/span><\/span>\n  client = Cats::Client.new\n  redirect_to action:<\/span> :index<\/span>, image_url:<\/span> client.get_picture_url\nend<\/span><\/code><\/span>Code language:<\/span> Ruby<\/span> (<\/span>ruby<\/span>)<\/span><\/small><\/pre>\n\n\n
<\/div>\n\n\n\n
Building a basic generator<\/h2>\n\n\n\n
Our cat picture fetching service is now working, but remember the service was suposed to be for animals not only cats. Let’s add the option to retrieve dog pictures. But before that, you will notice, the client is probably something we will repeat a lot so it is a good candidate for making a generator (Finally!).<\/p>\n\n\n\n
Let’s generate a generator:<\/p>\n\n\n
rails generate generator AnimalApiClient<\/code><\/span><\/pre>\n\n\n
This will generate some files under lib\/generators. First we are going to create a file in the templates folder and call it client.rb.tt where we are going to copy the code from the cats client and make a few modifications, removing some specific data and using the class_name method to name our module. Think of this like something similar to the erb files that render our views. Check all the methods<\/a> provided by the NamedBased class that you can use to generate the file.<\/p>\n\n\n\n
lib\/generators\/animal_api_client\/templates\/client.rb.tt<\/strong><\/p>\n\n\n
module<\/span> <%= class_name<\/span> %><\/span>\n\n  class<\/span> Client<\/span><\/span>\n    include<\/span> HTTParty\n\n    base_uri ''<\/span>\n\n    def<\/span> initialize<\/span><\/span>\n    end<\/span>\n\n    def<\/span> get_picture_url<\/span><\/span>\n      response = self<\/span>.class<\/span>.get<\/span>('')<\/span>\n      # return the url<\/span>\n    end<\/span>\n\n  end<\/span>\nend<\/span><\/code><\/span>Code language:<\/span> Ruby<\/span> (<\/span>ruby<\/span>)<\/span><\/small><\/pre>\n\n\n
That is going to be our template, and now let’s move on to the actual generator that is going to use this template to generate our new clients.<\/p>\n\n\n\n
lib\/generators\/animal_api_client\/animal_api_client_generator.rb<\/strong><\/p>\n\n\n
class<\/span> AnimalApiClientGenerator<\/span> < Rails::Generators::NamedBase<\/span><\/span>\n<\/span><\/span>  source_root File.expand_path('templates'<\/span>, __dir__<\/span>)\n<\/span><\/span>\n<\/span><\/span>  def<\/span> create_client_file<\/span><\/span>\n<\/span><\/span>    template \"client.rb\"<\/span>, File.join(\"app\/services\"<\/span>, file_name, \"client.rb\"<\/span>)\n<\/span><\/span>  end<\/span>\n<\/span><\/span>end<\/span>\n<\/span><\/span>\n<\/span><\/span><\/code><\/span>Code language:<\/span> Ruby<\/span> (<\/span>ruby<\/span>)<\/span><\/small><\/pre>\n\n\n
You can define all the methods you want in the generator class, they will be called in the order they are defined. <\/p>\n\n\n\n
Using the generator<\/h4>\n\n\n\n
We can now call the generator to create new clients, let’s create a new client, this time to retrieve picture of dogs:<\/p>\n\n\n
rails g animal_api_client dogs<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
That will create the file app\/services\/dogs\/client.rb with the following content:<\/p>\n\n\n
module<\/span> Dogs<\/span><\/span>\n<\/span><\/span>\n<\/span><\/span>  class<\/span> Client<\/span><\/span>\n<\/span><\/span>    include<\/span> HTTParty\n<\/span><\/span>\n<\/span><\/span>    base_uri ''<\/span>\n<\/span><\/span>\n<\/span><\/span>    def<\/span> initialize<\/span><\/span>\n<\/span><\/span>    end<\/span>\n<\/span><\/span>\n<\/span><\/span>    def<\/span> get_picture_url<\/span><\/span>\n<\/span><\/span>      response = self<\/span>.class<\/span>.get<\/span>('')<\/span>\n<\/span><\/span>      # return the url<\/span>\n<\/span><\/span>    end<\/span>\n<\/span><\/span>\n<\/span><\/span>  end<\/span>\n<\/span><\/span>end<\/span>\n<\/span><\/span><\/code><\/span>Code language:<\/span> Ruby<\/span> (<\/span>ruby<\/span>)<\/span><\/small><\/pre>\n\n\n
# config\/routes.rb<\/span>\npost 'animal_pictures\/get_dog'<\/span>\n\n# app\/views\/animal_pictures\/index.html.erb<\/span>\n<%= button_to \"Dogs\"<\/span>, action:<\/span> :get_dog<\/span> %>\n\n# app\/controllers\/animal_pictures_controller.rb<\/span>\ndef<\/span> get_dog<\/span><\/span>\n  client = Dogs::Client.new\n  redirect_to action:<\/span> :index<\/span>, image_url:<\/span> client.get_picture_url\nend<\/span><\/code><\/span>Code language:<\/span> Ruby<\/span> (<\/span>ruby<\/span>)<\/span><\/small><\/pre>\n\n\n
<\/div>\n\n\n\n
Beyond the basics<\/h2>\n\n\n\n
Our project now can retrieve pictures of cats and dogs. And although replicating the dogs part was easier, I still have to modify another 3 files with repetitive code! We can make it even easier. Let’s add something else to our generator, we will insert some code into our existing files<\/p>\n\n\n\n
<\/div>\n\n\n\n
route<\/h4>\n\n\n\n
You can add routes to your routes.rb file using the route <\/a>method. In this case we will add a post route using the singular_table_name method to name the endpoint:<\/p>\n\n\n
def<\/span> add_routes<\/span><\/span>\n  route \"post 'animal_pictures\/get_#{singular_table_name}<\/span>'\"<\/span>\nend<\/span><\/code><\/span>Code language:<\/span> Ruby<\/span> (<\/span>ruby<\/span>)<\/span><\/small><\/pre>\n\n\n
<\/div>\n\n\n\n
inject_into_class<\/h4>\n\n\n\n
For the code  in the controller we are going to take another approach, we will use the inject_into_class <\/a>method, that puts whatever content we provide just after the class declaration, then again we will be using the singular_table_name and class_name helper methods<\/p>\n\n\n
def<\/span> add_to_controller<\/span><\/span>\n  inject_into_class \"app\/controllers\/animal_pictures_controller.rb\"<\/span>, AnimalPicturesController, <<~RUBY.indent(2)\n    def get_#{singular_table_name}<\/span>\n      client = #{class_name }<\/span>::Client.new\n      redirect_to action: :index, image_url: client.get_picture_url\n    end\n  RUBY<\/span>\nend<\/span><\/code><\/span>Code language:<\/span> Ruby<\/span> (<\/span>ruby<\/span>)<\/span><\/small><\/pre>\n\n\n
<\/div>\n\n\n\n
insert_into_file<\/h4>\n\n\n\n
Finally for our view we will use the insert_into_file<\/a> method, this will allow us to specify an anchor for our content with the before: or after: options. In our case to facilitate our work we are going to modify our view and wrap our buttons in a div with a unique id, this div will serve as the anchor.<\/p>\n\n\n\n
app\/views\/animal_pictures\/index.html.erb<\/strong><\/p>\n\n\n
<div<\/span> id<\/span>=\"actions\"<\/span>><\/span>\n    <%=<\/span><\/span><\/span> button_to \"Cats\"<\/span>, action:<\/span> :get_cat<\/span> <\/span>%><\/span>\n    <%=<\/span><\/span><\/span> button_to \"Dogs\"<\/span>, action:<\/span> :get_dog<\/span> <\/span>%><\/span>\n<\/div<\/span>><\/span><\/span><\/code><\/span>Code language:<\/span> ERB (Embedded Ruby)<\/span> (<\/span>erb<\/span>)<\/span><\/small><\/pre>\n\n\n
Now let’s write the method in our generator:<\/p>\n\n\n
def<\/span> add_to_view<\/span><\/span>\n  insert_into_file \"app\/views\/animal_pictures\/index.html.erb\"<\/span>, after:<\/span> '<div id=\"actions\">'<\/span> do<\/span> <<~ERB.indent(4)\n\n      <%= button_to \"#{class_name}<\/span>\", action: :get_#{singular_table_name}<\/span> %>\n    ERB<\/span>\n  end<\/span>\nend<\/span><\/code><\/span>Code language:<\/span> Ruby<\/span> (<\/span>ruby<\/span>)<\/span><\/small><\/pre>\n\n\n
This code will insert the button right after the opening div tag. <\/p>\n\n\n\n
rails g animal_api_client ducks<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
We will have this result:<\/p>\n\n\n
# config\/routes.rb<\/span>\nRails.application.routes.draw do<\/span>\n  post 'animal_pictures\/get_duck'<\/span>\n  get 'animal_pictures\/index'<\/span>\n  post 'animal_pictures\/get_cat'<\/span>\n  post 'animal_pictures\/get_dog'<\/span>\n  # For details on the DSL available within this file, see https:\/\/guides.rubyonrails.org\/routing.html<\/span>\nend<\/span>\n\n# app\/controllers\/animal_pictures_controller.rb<\/span>\nclass<\/span> AnimalPicturesController<\/span> < ApplicationController<\/span>\n  def<\/span> get_duck<\/span><\/span>\n    client = Ducks::Client.new\n    redirect_to action:<\/span> :index<\/span>, image_url:<\/span> client.get_picture_url\n  end<\/span>\n  def<\/span> index<\/span><\/span>\n    @image_url = params[:image_url<\/span>]\n  end<\/span>\n\n  def<\/span> get_cat<\/span><\/span>\n    client = Cats::Client.new\n    redirect_to action:<\/span> :index<\/span>, image_url:<\/span> client.get_picture_url\n  end<\/span>\n\n  def<\/span> get_dog<\/span><\/span>\n    client = Dogs::Client.new\n    redirect_to action:<\/span> :index<\/span>, image_url:<\/span> client.get_picture_url\n  end<\/span>\n\nend<\/span>\n\n# app\/services\/ducks\/client.rb<\/span>\nmodule<\/span> Ducks<\/span><\/span>\n\n  class<\/span> Client<\/span><\/span>\n    include<\/span> HTTParty\n\n    base_uri ''<\/span>\n\n    def<\/span> initialize<\/span><\/span>\n    end<\/span>\n\n    def<\/span> get_picture_url<\/span><\/span>\n      response = self<\/span>.class<\/span>.get<\/span>('')<\/span>\n      # return the url<\/span>\n    end<\/span>\n\n  end<\/span>\nend<\/span><\/code><\/span>Code language:<\/span> Ruby<\/span> (<\/span>ruby<\/span>)<\/span><\/small><\/pre>\n\n\n
app\/views\/animal_pictures\/index.html.erb<\/strong><\/p>\n\n\n
<h1<\/span>><\/span>AnimalPictures#index<\/h1<\/span>><\/span>\n\n<%<\/span><\/span><\/span> unless<\/span> @image_url.nil<\/span>? <\/span>%><\/span>\n    <%=<\/span><\/span><\/span> image_tag @image_url, size:<\/span>\"512x512\"<\/span> <\/span>%><\/span>\n<%<\/span><\/span><\/span> end<\/span><\/span>%><\/span>\n\n<div<\/span> id<\/span>=\"actions\"<\/span>><\/span>\n    <%=<\/span><\/span><\/span> button_to \"Ducks\"<\/span>, action:<\/span> :get_duck<\/span> <\/span>%><\/span>\n\n    <%=<\/span><\/span><\/span> button_to \"Cats\"<\/span>, action:<\/span> :get_cat<\/span> <\/span>%><\/span>\n    <%=<\/span><\/span><\/span> button_to \"Dogs\"<\/span>, action:<\/span> :get_dog<\/span> <\/span>%><\/span>\n<\/div<\/span>><\/span>\n<\/span><\/code><\/span>Code language:<\/span> ERB (Embedded Ruby)<\/span> (<\/span>erb<\/span>)<\/span><\/small><\/pre>\n\n\n
Now we only have to add the specifics for the API we are going to use and it will be READY!.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Final thoughts<\/h2>\n\n\n\n
I hope this helped you know the capabilities of the Rails generators, especially when you have an application that requires a lot of integrations, or new features that have a very similar starting point. This may save you a lot of time. Complete code is in my repo<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
In the last weeks I have been using mason to generate some boiler plate code for my personal project, may have to write about it some other time. So the idea of templating was sitting in my head at all times. Then at my job I got assigned a task, a very common task actually, a third party integration. So […]<\/p>\n","protected":false},"author":1,"featured_media":165,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"om_disable_all_campaigns":false,"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[24],"tags":[98,94],"class_list":["post-237","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-learning","tag-api","tag-ruby-on-rails-en"],"aioseo_notices":[],"_links":{"self":[{"href":"https:\/\/gerardomiranda.dev\/blog\/wp-json\/wp\/v2\/posts\/237","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/gerardomiranda.dev\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/gerardomiranda.dev\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/gerardomiranda.dev\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/gerardomiranda.dev\/blog\/wp-json\/wp\/v2\/comments?post=237"}],"version-history":[{"count":15,"href":"https:\/\/gerardomiranda.dev\/blog\/wp-json\/wp\/v2\/posts\/237\/revisions"}],"predecessor-version":[{"id":259,"href":"https:\/\/gerardomiranda.dev\/blog\/wp-json\/wp\/v2\/posts\/237\/revisions\/259"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/gerardomiranda.dev\/blog\/wp-json\/wp\/v2\/media\/165"}],"wp:attachment":[{"href":"https:\/\/gerardomiranda.dev\/blog\/wp-json\/wp\/v2\/media?parent=237"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/gerardomiranda.dev\/blog\/wp-json\/wp\/v2\/categories?post=237"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/gerardomiranda.dev\/blog\/wp-json\/wp\/v2\/tags?post=237"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
Let’s run our generator again, this time we will be fetching duck pictures<\/a><\/p>\n\n\n
Now we just have to update the base_uri, the endpoint and return the appropriate data, we will use shibe API<\/a>. Next don’t forget to add the route, the button in the view and the method in the controller:<\/p>\n\n\n
With this we get a button that when pressed will show the picture, but wait… it always shows the same picture. To remedy that we will build a little client to call an API<\/a> that will provide a different picture every time:<\/p>\n\n\n\n