How to create Rails Generators (Rails 3 and above)

General

Programatically invoke Rails generators
: Require the generator, instantiate it and invoke it (because generators are Thor::Groups, you need to invoke them with invoke_all). Example:

Copy    require 'generators/wheelie/haml/haml_generator'
    Generators::HamlGenerator.new('argument').invoke_all

Other ways: Rails invokes its generators with Rails::Generators.invoke ARGV.shift, ARGV. From inside a Rails generator, you may call the inherited Thor method invoke(args=[], options={}, config={}) Show archive.org snapshot . There also is a generate method which will run the generator in a subprocess. Call it with generate 'generator_name', 'command line args'.

Expected (hard-coded) directory structure of a generator

Copy#{generator namespace, e.g. rails}/
  #{generator name, e.g. model}/
    templates/
      ...
    #{generator name, e.g. model}_generator.rb
    USAGE

Templates

If you want to use the supplied template, directory and other template methods, you must call source_root 'path/to/templates' inside your generator. If you stick to the expected directory structure, this will do it:

Copysource_root File.expand_path('../templates', __FILE__)

To overwrite existing files, add the :force option: template 'config/database.yml', force: true

• Templates are evaluated in the context of the generator, so they have access to the generator's (private) methods, attributes etc.
• Corresponding Rails Guide Show archive.org snapshot
• Source of thor's template method Show archive.org snapshot

Hooks

• hook_for documentation Show archive.org snapshot
• Corresponding Rails Guide Show archive.org snapshot

Controller generators

Rails ships with a ResourceHelpers Show archive.org snapshot module. Require 'rails/generators/active_model' and include Rails::Generators::ResourceHelpers inside your generator class to have some helpers at hand, i.e. controller_class_name and controller_file_name.

Configuration

Rails generator templates are customizable. Their default template comes with the railties gem, but a custom template will be preferred. Put it here:

Copy#{Rails.root}/
   lib/
     templates/
       #{generator namespace, e.g. rails}/
         #{generator name, e.g. model}/
           #{template name, e.g. model.rb}

Notes

generator namespace

Some generators invoke other generators: rails:model calls active_record:model by default (depending on the selected ORM). Thus, the model template is looked for in lib/templates/active_record/model/model.rb.

template name

Should be the same as the generator name, but actually depends on the generator's implementation.

Generator output

To announce what you are doing in your generator, you can use the method say_status. Statuses used by Rails are:

Copysay_status :run, 'bundle install'
say_status :identical, :blue, 'some_file'
say_status :remove, :green, 'some_file'
say_status :create, :green, 'some_file'
say_status :skip, :yellow
say_status :conflict, :red

Note that standard methods like template are already calling say_status.

General caveats

Heads up when defining a class_option :attributes

Rails::Generators::NamedBase#initialize will automatically parse attributes into Rails::Generators::GeneratedAttributes.