Just today I went to start and found the merb plugin generator wasn't able to generate generators. Now just to move on from that fairly circular sentence, a quick call to DrNic and he had it sorted pretty quickly. The end result is, that as of today, you'll need to install merb from trunk to follow this. That or wait until merb 0.5.0 is released officially.
Generate a Merb PluginMerb comes with an option to build the skeleton of a plugin inside the merb command.
$ merb -P merbful_authenticationAs you can see it's very simple to generate a merb plugin. You could call rake gem in that directory and it will build the gem for you automatically.
From here it's just like any other gem. When you add new files, be sure to add them to the gemspec in the Rakefile.
For the specific case of merbful_authentication, I want to have a generator that is available for all merb projects, and also generators with the relevant code for datamapper, activerecord, and sequel. This is a pretty important way to help support merb's ORM agnosticness.
Merb makes use of rubigen scopes. All merb projects have the merb scope and in your app when you select which orm to use via use_orm the ORM scope is selected automatically. The available scopes in a merb application at the moment are
- merb_default - (used when no orm is selected)
How to Use Scopes?When you make your generators, you should apply a scope to them. What this does is allows your gem to behave itself according to the configuration the user has setup. The way I'll setup the generators structure in merbful_authentication will be:
Why this is useful, is that the merb generators are always available, so we can always call the authentication generator in a merb app. This in turn will have a dependency on the authentication_model generator. This is where the magic happens. So if the app has:
Scope : datamapper
The authentication_model generator defined in datamapper_generators will be active and therefore used.
Scope : activerecord
The authentication_model generator defined in activerecord_generators will be active and used instead
This is the way merb generators support the different syntaxes of models and controllers when you use script/generate resource or similar. The testing frameworks will work the same way.
How to Generate a Generator with ScopeTo generate your generator with the required scope, it is really simple. In the root directory of your generated plugin:
$ ruby script/generate component_generator authentication merbThere are also a whole heap of instructions on what to do next that are put up on the screen.
This will generate the authentication generator in the merb scope. See the documentation for rubigen to see how to use your shiny new generator. It's pretty much the same that you'd do for rails.
So then to make the datamapper generator
ruby script/generate component_generator authentication_model datamapperI don't want this to show in the list of available generators when you run ruby script/generate so I will delete the USAGE file to prevent it showing up in that list.
Inside the merbful_authentication.rb (your_plugin.rb) file is the place to put your hook script. Similar to the init.rb file in rails plugins.
A note about plugins in general for merb. To mixin behavior to views and controllers you would include into and extend:
Views:- Merb::ViewContext (class)
- All controllers - Merb::AbstractController
- Just web controllers - Merb::Controller (or Application)
- Just Part controllers - Merb::PartController
- Just Mail controllers - Merb::MailController