Rails templates 32

Posted by pratik
on Thursday, December 04

So now that Edge Rails got templates ( Thanks to Jeremy ) I just wanted to give a top level overview.

Templates are simple ruby files containing DSL for adding plugins/gems/initializers etc. to your freshly created Rails project. To apply the template, you need to provide rails generator with location of the template you wish to apply, using -m option :



rails blog -m ~/template.rb

Thanks to the magic of open-uri, the template location can be a URL too :



rails blog -m http://gist.github.com/31208.txt

You can even apply templates to your existing Rails application using rails:template rake task and supplying LOCATION environment variable :



rake rails:template LOCATION=~/template.rb

A very simple template would look like :

1
2
3
4
5
6
7
8
9

# template.rb
run "rm public/index.html"
generate(:scaffold, "person name:string")
route "map.root :controller => 'people'"
rake("db:migrate")

git :init
git :add => "."
git :commit => "-a -m 'Initial commit'"

That’s very self explanatory. Here are the key methods for the template DSL :

gem(name, options = {})

Adds a config.gem entry for the supplied gem to generated application’s config/environment.rb

So if your application depends on bj and hpricot :

1
2

gem "bj"
gem "hpricot", :version => '0.6', :source => "http://code.whytheluckystiff.net"

Please note that this will NOT install the gems for you. So you may want to run rake gems:install:



rake "gems:install"

And let Rails take care of installing the required gems if they’re not already installed.

plugin(name, options = {})

Installs a plugin to the generated application.

Plugin can be installed from Git :



plugin 'authentication', :git => 'git://github.com/foor/bar.git'

You can even install plugins as git submodules :



plugin 'authentication', :git => 'git://github.com/foor/bar.git', :submodule => true

Please note that you need to git :init before you can install a plugin as a submodule

Or use plain old SVN :



plugin 'wtfsvn' :svn => 'svn://crap.com/wtf/trunk'

initializer(filename, data = nil, &block)

Adds an initializer to the generated application’s config/initializers directory.

So personally, I like using Object#not_nil? and Object#not_blank? :

1
2
3
4
5
6
7
8
9
10
11

initializer 'bloatlol.rb', <<-CODE
class Object
  def not_nil?
    !nil?
  end
  
  def not_blank?
    !blank?
  end
end
CODE

Similarly lib() creates a file in lib/ directory and vendor() creates a file in vendor/ directory. There is also file(), which accepts a relative path from RAILS_ROOT and creates all the directories/file needed :

1
2
3
4

file 'app/components/foo.rb', <<-CODE
class Foo
end
CODE

That’ll create app/components directory and put foo.rb in there.

rakefile(filename, data = nil, &block)

Creates a new rake file under lib/tasks with the supplied tasks :

1
2
3
4
5
6
7
8
9

rakefile("bootstrap.rake") do
  <<-TASK
    namespace :boot do
      task :strap do
        puts "i like boots!"
      end
    end
  TASK
end

And that creates lib/tasks/bootstrap.rake with a boot:strap rake task!

generate(what, args)

Runs the supplied rails generator with given arguments. For example, I love to scaffold some whenever I’m playing with Rails :



generate(:scaffold, "person", "name:string", "address:text", "age:number")

run(command)

Executes an arbitrary command. Just like the backticks. My main use case is to remove public/index.html :



run "rm public/index.html"

rake(command, options = {})

So you scaffolded, but who’s gonna run the db:migrate rake task !? Here’s who :



rake "db:migrate"

Simple enough.

You can also run rake tasks in a different rails environment :



rake "db:migrate", :env => 'production'

Or even use sudo :



rake "gems:install", :sudo => true

route(routing_code)

This adds a routing entry to config/routes.rb file. In above steps, we generated a person scaffold and also removed public/index.html. Now to make PeopleController#index as the default page for the application :



route "map.root :controller => :person"

Voila!

inside(dir)

I have my edge rails lying at ~/commit-rails/rails. So every time i have to manually symlink edge from my new app. But now :

1
2
3

inside('vendor') do
  run "ln -s ~/commit-rails/rails rails"
end

So inside() runs the command from the given directory.

ask(question)

ask gives you a chance to get some feedback from the user and use it in your templates. Lets say you want your user to name the new shiny library you’re adding :

1
2
3
4
5
6
7

lib_name = ask("What do you want to call the shiny library ?")
lib_name << ".rb" unless lib_name.index(".rb")

lib lib_name, <<-CODE
class Shiny
end
CODE

yes?(question) or no?(question)

And you can even ask questions from templates and decide the flow based on user’s answer. Lets say you want to freeze rails only if the user want to :



rake("rails:freeze:gems") if yes?("Freeze rails gems ?")

no?(question) acts just the opposite.

git(:must => “-a love”)

As we all love git/hub, Rails templates let you do the git stuff too !

1
2
3

git :init
git :add => "."
git :commit => "-a -m 'Initial commit'"

And bort ?

Here’s what a bort template would look like :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# bort.rb
inside('vendor') do
  run "ln -s ~/commit-rails/rails rails"
end

plugin 'rspec', 
  :git => 'git://github.com/dchelimsky/rspec.git'
plugin 'rspec-rails', 
  :git => 'git://github.com/dchelimsky/rspec-rails.git'
plugin 'exception_notifier', 
  :git => 'git://github.com/rails/exception_notification.git'
plugin 'open_id_authentication', 
  :git => 'git://github.com/rails/open_id_authentication.git'
plugin 'asset_packager', 
  :git => 'http://synthesis.sbecker.net/pages/asset_packager'
plugin 'role_requirement', 
  :git => 'git://github.com/timcharper/role_requirement.git'
plugin 'restful-authentication', 
  :git => 'git://github.com/technoweenie/restful-authentication.git'
 
gem 'mislav-will_paginate', :version => '~> 2.2.3', 
  :lib => 'will_paginate',  :source => 'http://gems.github.com'
gem 'rubyist-aasm'
gem 'ruby-openid'
 
rake("gems:install", :sudo => true)

generate("authenticated", "user session")
generate("rspec")

Shamelessly inspired/yanked from Jeremy’s templates repo

Save that code in bort.rb and :



[lifo@null Rails]$ ruby ~/commit-rails/rails/railties/bin/rails bortapp -m bort.rb

Contribute

If you like this template stuff and want to share your templates with the rest of us, please contribute to Jeremy’s rails-templates project – which will be a collection of Rails templates.

And as usual, any bugs/feature requests can go to Rails lighthouse

UPDATE 1 Add an example of installing plugins as a git submodule. Thanks to Peter Cooper for the patch. UPDATE 2 Add an example of rake rails:template LOCATION=foo task

Comments

Leave a response

  1. Paul Barry – December 04, 2008 @ 02:04 AM

    Wow. This is fantastic, can’t wait to try it out.

  2. Kevin Marsh – December 04, 2008 @ 02:36 AM

    Wow, great to see so much cool stuff in Rails coming so quickly!

  3. grosser – December 04, 2008 @ 07:33 AM

    looks promising, at last no more template-rails-applications to customize, a simple config can do :)

  4. Luis – December 04, 2008 @ 10:45 AM

    Awesome! I was doing this with shell scripts, generators and such. This is great!

  5. Jerome – December 04, 2008 @ 01:41 PM

    Hmm, that is awesome!

    Will cut quite some development time at the beginning, just like Bort does, but now I can take it much further much more easily!

  6. Jim Neath – December 04, 2008 @ 01:49 PM

    Looks like I’ll have less maintaining to do on Bort now :)

  7. Harry Jr. – December 04, 2008 @ 01:51 PM

    But most of that stuff is easily accomplished with a Rake task, apart from maybe the route and initializer-stuff. Why not add it as rake-stuff, like Vlad?

  8. Pratik – December 04, 2008 @ 02:02 PM

    @Jim : Heh. Thanks for your work on Bort! If you run into any issues with rails templates, please do let me know. Same for feature requests too.

    @Harry : That’s a good idea. Making this a rake task would be a 3-4 lines of code. Just need to call Rails::TemplateRunner.new(Rails.root, ‘template_path’) and you’re done. Probably you can play around with that and submit a patch or something.

  9. subbu – December 05, 2008 @ 06:53 AM

    Ah! Things move so fast. Few days back it was bort. Now templates. Some rake tasks later to simplify even these templates. Good stuff.

  10. Peter Cooper – December 05, 2008 @ 07:12 AM

    This is absolutely awesome. I’m enjoying playing with it.

    Now.. it might be a bit late or I haven’t had enough caffeine, but is there a nice-ish way of using git submodules in with this? For example, those plugins that are being installed from git.

  11. Pratik – December 05, 2008 @ 08:19 AM

    @Peter : Not at the moment. Jeremy had support for Braid in initial versions of rg. But we decided to remove that and wait to see what people use and demand for. I think adding support for git submodules sound reasonable and easy.

    I don’t really know how git submodules work, so if someone wants to help me with a patch or submit one, you’re most welcome!

  12. Peter Cooper – December 05, 2008 @ 10:14 AM

    I imagine someone will come up with an idea quicker than me but I’ll definitely have a look :) Git submodules make life really easy.

    Also, the example template in the post has an interesting quirk. Might just be me, so I’m intrigued. The line:

    route “map.root :controller => :person”

    The final app won’t work with that for me. It needs to be ‘people’ rather than :person. I’m pointing it out, though, in case I’m doing something boneheaded and you actually can use symbols in routes (something I’ve wanted for a long time).

  13. Pratik – December 05, 2008 @ 10:57 AM

    Oops..your’re right. Updated it in the post. Thanks!

  14. lomakin – December 05, 2008 @ 10:59 AM

    Pretty cool!!!

  15. Peter Cooper – December 05, 2008 @ 11:06 AM

    Just submitted a patch for it:

    http://rails.lighthouseapp.com/projects/8994/tickets/1517-option-for-template-generator-to-install-plugins-as-git-submodules

    Might ultimately not be the right way to do it though, but it works for me here.

    The only other alternative I can think of would be to add the submodule feature to /script/plugin instead.. that might be a better idea really.. I’ll take a look at that next.

  16. Rahsun McAfee – December 05, 2008 @ 03:25 PM

    Hats off to Jeremy and Pratik. This feature is wonderful. I can’t wait to rock it.

  17. Spyou – December 05, 2008 @ 03:33 PM

    Thanks a lot for this feature.

    This is going to be very useful

  18. Carlo Pecchia – December 05, 2008 @ 04:08 PM

    Nice! Really nice feature… I’m sure an interesting “marketplace” of pre-configured application will emerge. And that’s another weapon for Ruby communities..!

  19. Pratik – December 05, 2008 @ 11:25 PM

    @Peter Applied the patch. Thanks!

  20. Natts – December 06, 2008 @ 12:52 AM

    Just translated and posted this in russian at my blog. Trackbacks and backlinks are in place =)

    Than you, folks! This is just great.. I’ve tried it out and created some templates. Will contribute tomorrow / in some days.

  21. Liam Morley – December 06, 2008 @ 05:14 AM

    Hey, that’s pretty awesome.

  22. Anil Wadghule – December 08, 2008 @ 05:03 AM

    This is really FTW!

  23. Pratik – December 08, 2008 @ 02:08 PM

    @Harry Jr : I also added a rake task to apply a template to an existing Rails application. Check UPDATE 2 :)

  24. Arhimed – December 09, 2008 @ 09:44 PM

    Impressive!

  25. Eric Berry – December 11, 2008 @ 04:49 PM

    Excellent! Now we need a site where people can post their application templates and be able to categorize and rate them. Any takers?

  26. Sergio Romano – December 12, 2008 @ 01:05 PM

    In Assembla we have already done it (although not using this wonderful new feature).

    You can create your own template online workspace, put any code you want in your subversion (git or mercurial) repository and add any other documentation or tool you think you will need for your projects. Then, you can post it in our preconfigured package catalog (http://www.assembla.com/preconfigured_spaces) and allow other users to copy it.

    As an example, we have created a Rails package that comes with a Subversion Repository which includes a Rails Skeleton with some useful deploy tasks. And also, some documentation for developers to setup RoR or to configure their servers to deploy.

    Check the Ruby on Rails package here: http://www.assembla.com/preconfigured_spaces/10-Ruby-on-Rails-Package It’s FREE for Open Source projects

  27. Miroslav – December 14, 2008 @ 08:30 PM

    This is so cool, but how do i get rails command up to edge version?? with rails 2.2.2 i of course get error “invalid option: -m” i know how to install edge rails in existing app, but still, i think it does not replace my rails command as far as i have googled…

    thx for help

  28. Brian Hardy – December 19, 2008 @ 04:50 PM

    To get your bort template to work with edge rails (as of 12/18/2008), I had to modify the gem lines for rubyist-aasm and ruby-openid as follows:

    gem ‘rubyist-aasm’, :lib => ‘aasm’ gem ‘ruby-openid’, :lib => ‘openid’

    That took me a while to figure out, but otherwise, great stuff!

  29. Sam – December 27, 2008 @ 08:38 PM

    Nice article, certainly cleared a few things up for me. I love how fast great ideas for rails can quickly be implemented into the core.

  30. Andrew Timberlake – December 28, 2008 @ 12:19 PM

    @miroslav To run the rails command out of edge rails, run the command with the full path – <edge_rails_directory>/railties/bin/rails -m <template_path> <project_path>

  31. LacKac – December 31, 2008 @ 11:52 AM

    I’ve created a modularized collection of application templates called App LEGO: http://github.com/lackac/app_lego/tree/master Some ideas came from Jeremy’s template repo, but this one is more like a collection of modules working well together. Check it out. It also has support for braid.

  32. Daniel Lopes – December 31, 2008 @ 03:56 PM

    Amazing feature… It will be very usefull, but my question is about projects like Bort … This kind of projects generate a skeleton for some repeated tasks like login ( with all bells and wishes like roles, email activation, reminder and etc ), exception notification, localization and etc…

    It will not be possible with this new builtin feature, right? Projects like bort still valid?

Comment





Sections

Tags

 Subscribe in a reader