From 6d87cd028b32570973450424db164e5405a0ee13 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sat, 17 Mar 2012 08:32:49 -0700 Subject: moves the guides up to the root directory --- guides/source/rails_application_templates.textile | 215 ++++++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 guides/source/rails_application_templates.textile (limited to 'guides/source/rails_application_templates.textile') diff --git a/guides/source/rails_application_templates.textile b/guides/source/rails_application_templates.textile new file mode 100644 index 0000000000..f50ced3307 --- /dev/null +++ b/guides/source/rails_application_templates.textile @@ -0,0 +1,215 @@ +h2. Rails Application Templates + +Application templates are simple Ruby files containing DSL for adding 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 templates to generate/customize Rails applications +* Write your own reusable application templates using the Rails template API + +endprologue. + +h3. Usage + +To apply a template, you need to provide the Rails generator with the location of the template you wish to apply, using -m option. This can either be path to a file or a URL. + + +$ rails new blog -m ~/template.rb +$ rails new blog -m http://example.com/template.rb + + +You can use the rake task +rails:template+ to apply templates to an existing Rails application. The location of the template needs to be passed in to an environment variable named LOCATION. Again, this can either be path to a file or a URL. + + +$ rake rails:template LOCATION=~/template.rb +$ rake rails:template LOCATION=http://example.com/template.rb + + +h3. Template API + +Rails templates API is very self explanatory and easy to understand. Here's an example of a typical Rails template: + + +# template.rb +run "rm public/index.html" +generate(:scaffold, "person name:string") +route "root :to => 'people#index'" +rake("db:migrate") + +git :init +git :add => "." +git :commit => "-a -m 'Initial commit'" + + +The following sections outlines the primary methods provided by the API: + +h4. gem(name, options = {}) + +Adds a +gem+ entry for the supplied gem to the generated application’s +Gemfile+. + +For example, if your application depends on the gems +bj+ and +nokogiri+: + + +gem "bj" +gem "nokogiri" + + +Please note that this will NOT install the gems for you and you will have to run +bundle install+ to do that. + + +bundle install + + +h4. gem_group(*names, &block) + +Wraps gem entries inside a group. + +For example, if you want to load +rspec-rails+ only in +development+ and +test+ group: + + +gem_group :development, :test do + gem "rspec-rails" +end + + +h4. add_source(source, options = {}) + +Adds the given source to the generated application's +Gemfile+. + +For example, if you need to source a gem from "http://code.whytheluckystiff.net": + + +add_source "http://code.whytheluckystiff.net" + + +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?+: + + +initializer 'bloatlol.rb', <<-CODE +class Object + def not_nil? + !nil? + end + + def not_blank? + !blank? + end +end +CODE + + +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: + + +file 'app/components/foo.rb', <<-CODE +class Foo +end +CODE + + +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: + + +rakefile("bootstrap.rake") do + <<-TASK + namespace :boot do + task :strap do + puts "i like boots!" + end + end + TASK +end + + +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. + + +generate(:scaffold, "person", "name:string", "address:text", "age:number") + + +h4. run(command) + +Executes an arbitrary command. Just like the backticks. Let's say you want to remove the +public/index.html+ file: + + +run "rm public/index.html" + + +h4. rake(command, options = {}) + +Runs the supplied rake tasks in the Rails application. Let's say you want to migrate the database: + + +rake "db:migrate" + + +You can also run rake tasks with a different Rails environment: + + +rake "db:migrate", :env => 'production' + + +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: + + +route "root :to => 'person#index'" + + +h4. inside(dir) + +Enables you to run a command from the given directory. For example, if you have a copy of edge rails that you wish to symlink from your new apps, you can do this: + + +inside('vendor') do + run "ln -s ~/commit-rails/rails rails" +end + + +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: + + +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 + + +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: + + +rake("rails:freeze:gems") if yes?("Freeze rails gems ?") +no?(question) acts just the opposite. + + +h4. git(:command) + +Rails templates let you run any git command: + + +git :init +git :add => "." +git :commit => "-a -m 'Initial commit'" + -- cgit v1.2.3