diff options
Diffstat (limited to 'doc/users-guide.txt')
| -rw-r--r-- | doc/users-guide.txt | 218 |
1 files changed, 158 insertions, 60 deletions
diff --git a/doc/users-guide.txt b/doc/users-guide.txt index 927d478..5ad14b8 100644 --- a/doc/users-guide.txt +++ b/doc/users-guide.txt @@ -2423,71 +2423,85 @@ This section describes how to use Erubis with Ruby on Rails. .$$ Settings | rails-settings -.1) Add the following code to your 'config/environment.rb'. +Add the following code to your 'config/environment.rb' and restart web server. +This replaces ERB in Rails by Erubis entirely. - .? config/environment.rb - .-------------------- - require 'erubis/helpers/rails_helper' - #Erubis::Helpers::RailsHelper.engine_class = Erubis::Eruby # or Erubis::FastEruby - #Erubis::Helpers::RailsHelper.init_properties = {} - #Erubis::Helpers::RailsHelper.show_src = false - #Erubis::Helpers::RailsHelper.preprocessing = true - .-------------------- +.? config/environment.rb +.-------------------- +require 'erubis/helpers/rails_helper' +#Erubis::Helpers::RailsHelper.engine_class = Erubis::Eruby # or Erubis::FastEruby +#Erubis::Helpers::RailsHelper.init_properties = {} +#Erubis::Helpers::RailsHelper.show_src = nil +#Erubis::Helpers::RailsHelper.preprocessing = false +.-------------------- + +Options: + +.% Erubis::Helpers::RailsHelper.engine_class (=Erubis::Eruby) + Erubis engine class (default Erubis::Eruby). +.% Erubis::Helpers::RailsHelper.init_properties (={}) + Optional arguments for Erubis::Eruby#initialize() method (default {}). +.% Erubis::Helpers::RailsHelper.show_src (=nil) + Whether to print converted Ruby code into log file. + If true, Erubis prints coverted code into log file. + If false, Erubis doesn't. + If nil, Erubis prints when ENV['RAILS_ENV'] == 'development'. + Default is nil. +.% Erubis::Helpers::RailsHelper.preprocessing (=false) + Enable preprocessing if true (default false). - This will replace ERB in Rails by Erubis entirely. -.2) (Optional) apply the following patch to 'action_pack/lib/action_view/base.rb'. - - .? action_view_base_rb.patch - .-------------------- - --- lib/action_view/base.rb (original) - +++ lib/action_view/base.rb (working copy) - @@ -445,6 +445,11 @@ - end - end - - + # convert template into ruby code - + def convert_template_into_ruby_code(template) - + ERB.new(template, nil, @@erb_trim_mode).src - + end - + - # Create source code for given template - def create_template_source(extension, template, render_symbol, locals) - if template_requires_setup?(extension) - @@ -458,7 +463,7 @@ - "update_page do |page|\n#{template}\nend" - end - else - - body = ERB.new(template, nil, @@erb_trim_mode).src - + body = convert_template_into_ruby_code(template) - end - - @@template_args[render_symbol] ||= {} - .-------------------- - - This patch is included in erubis_2.X.X/contrib directory and the following is an - example to apply this patch. - - .? how to apply patch: - .==================== - $ cd /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.13.1/lib/action_view/ - $ sudo patch -p1 < /tmp/erubis_2.X.X/contrib/action_view_base_rb.patch - .==================== - - Notice that this patch is not necessary if you are using Ruby on Rails ver 1.1 or 1.2, but it is recommended. - -.3) Restart web server. - .==================== - $ ruby script/server - .==================== - -The setting is above all. +.#.2) (Optional) apply the following patch to 'action_pack/lib/action_view/base.rb'. +.# +.# .? action_view_base_rb.patch +.# .-------------------- +.# --- lib/action_view/base.rb (original) +.# +++ lib/action_view/base.rb (working copy) +.# @@ -445,6 +445,11 @@ +.# end +.# end +.# +.# + # convert template into ruby code +.# + def convert_template_into_ruby_code(template) +.# + ERB.new(template, nil, @@erb_trim_mode).src +.# + end +.# + +.# # Create source code for given template +.# def create_template_source(extension, template, render_symbol, locals) +.# if template_requires_setup?(extension) +.# @@ -458,7 +463,7 @@ +.# "update_page do |page|\n#{template}\nend" +.# end +.# else +.# - body = ERB.new(template, nil, @@erb_trim_mode).src +.# + body = convert_template_into_ruby_code(template) +.# end +.# +.# @@template_args[render_symbol] ||= {} +.# .-------------------- +.# +.# This patch is included in erubis_2.X.X/contrib directory and the following is an +.# example to apply this patch. +.# +.# .? how to apply patch: +.# .==================== +.# $ cd /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.13.1/lib/action_view/ +.# $ sudo patch -p1 < /tmp/erubis_2.X.X/contrib/action_view_base_rb.patch +.# .==================== +.# +.# Notice that this patch is not necessary if you are using Ruby on Rails ver 1.1 or 1.2, but it is recommended. +.# +.#.2) Restart web server. +.# .==================== +.# $ ruby script/server +.# .==================== +.# +.#The setting is above all. .$$ Preprosessing | rails-preprocessing -{{*(Experimental)*}} Erubis supports preprocessing of template files. Preprocessing make your Ruby on Rails application about 20-40 percent faster. To enable preprocessing, set Erubis::Helpers::RailsHelper.preprocessing to true in your 'environment.rb' file. @@ -2576,13 +2590,97 @@ Helper methods of Ruby on Rails are divided into two groups. Preprocessing is not available with these methods. +{{!CAUTHON:!}} link_to() in Ruby on Rails 2.0 doesn't work correctly with preprocessing. + + +.$$ Form Helpers for Preprocessing | rails-formhelpers + +Erubis provides form helper methods for preprocessing. +These are defined in 'erubis/helpers/rails_form_helper.rb'. +If you want to use it, require it and include Erubis::Helpers::RailsFormHelper in 'app/helpers/applition_helper.rb' + +.? app/helpers/xxx_helper.rb +.-------------------- +require 'erubis/helpers/rails_form_helper' +module ApplicationHelper + include Erubis::Helpers::RailsFormHelper +end +.-------------------- + +Form helper methods defined in Erubis::Helpers::RailsFormHelper are named as 'pp_xxxx' +('pp' represents preprocessing). + +Assume the following view template: + +.? _form.rhtml +.-------------------- + <p> + Name: <%= text_field :user, :name %> + </p> + <p> + Name: {{*[%= pp_text_field :user, :name %]*}} + </p> +.-------------------- + +Erubis preprocessor converts it to the following eRuby string: + +.? preprocessed +.-------------------- + <p> + Name: <%= text_field :user, :name %> + </p> + <p> + Name: {{*<input id="stock_name" name="stock[name]" size="30" type="text" value="<%=h @stock.name%>" />*}} + </p> +.-------------------- + +Erubis converts it to the following Ruby code: + +.? Ruby code +.-------------------- + _buf << ' <p> + Name: '; _buf << ( text_field :stock, :name ).to_s; _buf << ' +'; _buf << ' </p> + <p> + Name: <input id="stock_name" name="stock[name]" size="30" type="text" value="'; _buf << (h @stock.name).to_s; _buf << '" /> + </p> +'; +.-------------------- + +The above Ruby code shows that text_field() is called everytime when rendering, +but pp_text_field() is called only once when template is loaded. +This means that pp_text_field() with preprocessing makes view layer very fast. + +Module Erubis::Helpers::RailsFormHelper defines the following form helper methods. + +.* pp_render_partial(basename) +.* pp_form_tag(url_for_options={}, options={}, *parameters_for_url, &block) +.* pp_text_field(object_name, method, options={}) +.* pp_password_field(object_name, method, options={}) +.* pp_hidden_field(object_name, method, options={}) +.* pp_file_field(object_name, method, options={}) +.* pp_text_area(object_name, method, options={}) +.* pp_check_box(object_name, method, options={}, checked_value="1", unchecked_value="0") +.* pp_radio_button(object_name, method, tag_value, options={}) +.* pp_select(object, method, collection, options={}, html_options={}) +.* pp_collection_select(object, method, collection, value_method, text_method, options={}, html_options={}) +.* pp_country_select(object, method, priority_countries=nil, options={}, html_options={}) +.* pp_time_zone_select(object, method, priority_zones=nil, options={}, html_options={}) +.* pp_submit_tag(value="Save changes", options={}) +.* pp_image_submit_tag(source, options={}) + +Notice that pp_form_for() is not provided. + +{{!CAUTION:!}} These are not tested in Ruby on Rails 2.0. + + .$$ Others | rails-others .* ActionView::Helpers::CaptureHelper#capture() and ActionView::Helpers::Texthelper#concat() are available. -.* If Erubis::Helper::Rails.show_src is ture, Erubis prints converted Ruby code into log file (ex. 'log/development.log'). -If it is nil (default), Erubis prints converted Ruby code into log file only when development mode. - It is useful for debugging. +.* link_to() method in Ruby on Rails 2.0 doesn't work correctly with preprocessing. + +.* Form helper methods are not tested in Ruby on Rails 2.0. .* ERB::Util.h() is redefined if you require 'erubis/helpers/rails_helper.rb'. Original definition of ERB::Util.h() is the following and it is slow |