diff options
author | José Valim <jose.valim@gmail.com> | 2009-07-28 09:00:33 +0200 |
---|---|---|
committer | José Valim <jose.valim@gmail.com> | 2009-07-28 09:00:33 +0200 |
commit | d9aae2b56e64a4f417eaffa99e10cca274e928e7 (patch) | |
tree | 8438f6f784df9b252c0f834bc7cb9c369103d4cd /railties/guides/source/rails_application_templates.textile | |
parent | 5025ae610f89989f3e15241ec7065e3d443614d9 (diff) | |
parent | 9533e0eca76b1df68a90e1ebe395d7b6a59d8e91 (diff) | |
download | rails-d9aae2b56e64a4f417eaffa99e10cca274e928e7.tar.gz rails-d9aae2b56e64a4f417eaffa99e10cca274e928e7.tar.bz2 rails-d9aae2b56e64a4f417eaffa99e10cca274e928e7.zip |
Merge branch 'master' of git://github.com/rails/rails
Diffstat (limited to 'railties/guides/source/rails_application_templates.textile')
-rw-r--r-- | railties/guides/source/rails_application_templates.textile | 232 |
1 files changed, 226 insertions, 6 deletions
diff --git a/railties/guides/source/rails_application_templates.textile b/railties/guides/source/rails_application_templates.textile index 49cd5bf5f5..fc178fa44b 100644 --- a/railties/guides/source/rails_application_templates.textile +++ b/railties/guides/source/rails_application_templates.textile @@ -1,18 +1,238 @@ h2. Rails Application Templates -This guide covers the Rails application templates, By referring to this guide, you will be able to: +Application templates are simple ruby files containing DSL for adding plugins/gems/initializers etc. to your freshly created Rails project or an existing Rails project. + +By referring to this guide, you will be able to: -* Use existing templates to generate a customized Rails application -* Write your own reusable Rails application templates +* Use templates to generate/customize Rails applications +* Write your own reusable application templates using the Rails template API endprologue. -h3. Introduction +h3. Usage -Application templates are simple ruby files containing DSL for adding plugins/gems/initializers etc. to your freshly created Rails project or an existing Rails project. +To apply a template, you need to provide the Rails generator with the location of the template you wish to apply, using -m option : + +<shell> +$ rails blog -m ~/template.rb +</shell> + +It's also possible to apply a template using a URL : + +<shell> +$ rails blog -m http://gist.github.com/31208.txt +</shell> + +Alternatively, you can use the rake task +rails:template+ to apply a template to an existing Rails application : + +<shell> +$ rake rails:template LOCATION=~/template.rb +</shell> + +h3. Template API + +Rails templates API is very self explanatory and easy to understand. Here's an example of a typical Rails template : + +<ruby> +# 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'" +</ruby> + +The following sections outlines the primary methods provided by the API : + +h4. gem(name, options = {}) + +Adds a +config.gem+ entry for the supplied gem to the generated application’s +config/environment.rb+. + +For example, if your application depends on the gems +bj+ and +hpricot+ : + +<ruby> +gem "bj" +gem "hpricot", :version => '0.6', :source => "http://code.whytheluckystiff.net" +</ruby> + +Please note that this will NOT install the gems for you. So you may want to run the +rake gems:install+ task too : + +<ruby> +rake "gems:install" +</ruby> + +And let Rails take care of installing the required gems if they’re not already installed. + +h4. plugin(name, options = {}) + +Installs a plugin to the generated application. + +Plugin can be installed from Git : + +<ruby> +plugin 'authentication', :git => 'git://github.com/foor/bar.git' +</ruby> + +You can even install plugins as git submodules : + +<ruby> +plugin 'authentication', :git => 'git://github.com/foor/bar.git', + :submodule => true +</ruby> + +Please note that you need to +git :init+ before you can install a plugin as a submodule. + +Or use plain old SVN : + +<ruby> +plugin 'wtfsvn', :svn => 'svn://crap.com/wtf/trunk' +</ruby> + +h4. vendor/lib/file/initializer(filename, data = nil, &block) + +Adds an initializer to the generated application’s +config/initializers+ directory. + +Lets say you like using +Object#not_nil?+ and +Object#not_blank?+ : + +<ruby> +initializer 'bloatlol.rb', <<-CODE +class Object + def not_nil? + !nil? + end + + def not_blank? + !blank? + end +end +CODE +</ruby> + +Similarly +lib()+ creates a file in the +lib/+ directory and +vendor()+ creates a file in the +vendor/+ directory. + +There is even +file()+, which accepts a relative path from +RAILS_ROOT+ and creates all the directories/file needed : + +<ruby> +file 'app/components/foo.rb', <<-CODE +class Foo +end +CODE +</ruby> + +That’ll create +app/components+ directory and put +foo.rb+ in there. + +h4. rakefile(filename, data = nil, &block) + +Creates a new rake file under +lib/tasks+ with the supplied tasks : + +<ruby> +rakefile("bootstrap.rake") do + <<-TASK + namespace :boot do + task :strap do + puts "i like boots!" + end + end + TASK +end +</ruby> + +The above creates +lib/tasks/bootstrap.rake+ with a +boot:strap+ rake task. + +h4. generate(what, args) + +Runs the supplied rails generator with given arguments. For example, I love to scaffold some whenever I’m playing with Rails : + +<ruby> +generate(:scaffold, "person", "name:string", "address:text", "age:number") +</ruby> + +h4. run(command) + +Executes an arbitrary command. Just like the backticks. Let's say you want to remove the +public/index.html+ file : + +<ruby> +run "rm public/index.html" +</ruby> + +h4. rake(command, options = {}) + +Runs the supplied rake tasks in the Rails application. Let's say you want to migrate the database : + +<ruby> +rake "db:migrate" +</ruby> + +You can also run rake tasks with a different Rails environment : + +<ruby> +rake "db:migrate", :env => 'production' +</ruby> + +Or even use sudo : + +<ruby> +rake "gems:install", :sudo => true +</ruby> + +h4. route(routing_code) + +This adds a routing entry to the +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 : + +<ruby> +route "map.root :controller => :person" +</ruby> + +h4. 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 : + +<ruby> +inside('vendor') do + run "ln -s ~/commit-rails/rails rails" +end +</ruby> + +So +inside()+ runs the command from the given directory. + +h4. 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 : + +<ruby> +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 +</ruby> + +h4. yes?(question) or no?(question) + +These methods let you ask questions from templates and decide the flow based on the user’s answer. Lets say you want to freeze rails only if the user want to : + +<ruby> +rake("rails:freeze:gems") if yes?("Freeze rails gems ?") +no?(question) acts just the opposite. +</ruby> + +h4. git(:must => "-a love") + +Rails templates let you run any git command : + +<ruby> +git :init +git :add => "." +git :commit => "-a -m 'Initial commit'" +</ruby> h3. Changelog "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/78 -* April 17, 2009: Initial version by "Pratik":credits.html#lifo +* April 29, 2009: Initial version by "Pratik":credits.html#lifo |