Just over a month ago, I posted a project named rg to my Github account. It allows you to apply programmatic templates to your Rails applications so you can avoid all that monotonous setup every time you start a new app and avoid keeping it in Git where it tends to SCM rot. The code came about after discussing the concept with Pratik Naik on more than a few occasions, with both of us deciding that we were essentially too lazy to ever do anything about it.
Once I got over my laziness through boredom, I hacked out the code in a couple of days and posted it up. Over its first few weeks, it garnered a good number of watchers, patches, Twitter messages, users, complaints, and general interest from people. Soon after, Pratik and DHH floated the idea of perhaps integrating its features into core; excited by the prospect, I overcame my sloth and sallied forth to turn rg into a patch for the Rails application generator. As of today, that patch has been committed and rg is now part of Rails proper.
Awesome.
So, in celebration/honor/whatever of that, I thought it might be prudent to give people a little information about *how* to use it. It's quite simple really. Templates have a few core methods for doing things that can be grouped into a few groups: dependencies, file creation, and application actions.
Dependencies
The best part is that your templates can insert of any dependencies you might have. So, if you need to install a plugin (let's do restful_authentication), you can do something like this:
plugin "restful_authentication", :git => "git://github.com/technoweenie/restful-authentication.git"
Or if it's a gem...
gem "jeremymcanally-context"
This will install and vendor the gem.
File creation
It can also create arbitrary files for you (for example, if you have a config file for a service you always use) using a few methods (depending on where you want the file). The most primitive of these methods is file, which will
file "readme.txt", "This is the data!"
The first argument is the filename, the second is a string with the data to be put in the file. You don't have to do a quote form string; you can also do a heredoc:
file "todo.txt", <
You can also use the return value of a block...
file "readme.txt" do
puts "Tell me your name:"
name = gets
"Your project
by #{name}"
end
Even better, you can create files in specific locations. For example, initializer will create a new initializer file in config/initializers, vendor will create a file in the vendor/ directory, rakefile will create a new Rake file in lib/tasks, and lib will create a new code library file (or whatever) in the lib/ directory.
Application actions
There are also a few methods to do things to the application itself, such as freeze Rails (freeze!), capify the application (capify!), or generate things:
plugin "restful_authentication", :git => "git://github.com/technoweenie/restful-authentication.git"
generate :authenticated, "user session"
You can also run arbitrary Rake tasks:
rake "db:migrate"
If you put all this to use, this could save you a huge number of keystrokes and a lot of time every time you start an app.
Other stuff
There are a few other goodies in there if you need them. There's a git method that'll run a git command (git "pull" or what have you), some SCM interaction classes (only Git and Subversion so far, but I hope to see Hg, Bzr, and others contributed by people who use them), and some methods to interact with users:
name = ask("What is your name?")
# Must respond with "y" or "yes" or any capitalized variation thereof (e.g., "YeS")
`touch #{name}.txt` if yes?("Is #{name} really your name?")
# Must not respond with "y" or "yes"
`rm #{name}.txt` unless no?("Did you lie in the previous question?")
Those should satisfy 90% of user interaction needs; anything outside of that you need can be written in plain Ruby code.
Where do we go from here?
Well, to actually use your template, you need to supply the -m/--template parameter when generating an application:
rails yourapp -m /path/to/my/template.rb
rails newapp --template=http://gist.github.com/31208.txt
I'd really like to see a solid app template library be built, so to spur that effort, I've started a new repos on Github for that purpose: http://github.com/jeremymcanally/rails-templates
I've already put a few of the previously built in templates in there. If you have your own that you think people would be interested in, then fork it, merge yours in, and send me a pull request. If I think it's nifty enough, I'll merge it right in!
Otherwise, enjoy.
Comments [0]