diff options
Diffstat (limited to 'doc/users-guide.html')
| -rw-r--r-- | doc/users-guide.html | 275 |
1 files changed, 193 insertions, 82 deletions
diff --git a/doc/users-guide.html b/doc/users-guide.html index f2c99f0..dcb80ae 100644 --- a/doc/users-guide.html +++ b/doc/users-guide.html @@ -25,29 +25,29 @@ It has the following features. </p> <ul type="disc"> -<li><a href="#topics-benchmark">Very fast</a>, almost three times faster than ERB and about ten percent faster than eruby (implemented in C) +<li>Very fast, almost three times faster than ERB and about ten percent faster than eruby (implemented in C) </li> -<li><a href="#topics-caching">File caching of converted Ruby script support</a> +<li>File caching of converted Ruby script support </li> -<li><a href="#tut-escape">Auto escaping support</a> +<li>Auto escaping support </li> -<li><a href="#tut-trim">Auto trimming spaces around '<% %>'</a> +<li>Auto trimming spaces around '<% %>' </li> -<li><a href="#tut-pattern">Embedded pattern changeable</a> (default '<% %>') +<li>Embedded pattern changeable (default '<% %>') </li> -<li><a href="#tut-pi">Enable to handle Processing Instructions (PI) as embedded pattern</a> (ex. '<?rb ... ?>') +<li>Enable to handle Processing Instructions (PI) as embedded pattern (ex. '<?rb ... ?>') </li> -<li><a href="#lang">Multi-language support</a> (Ruby/PHP/C/Java/Scheme/Perl/Javascript) +<li>Multi-language support (Ruby/PHP/C/Java/Scheme/Perl/Javascript) </li> -<li><a href="#tut-context">Context object available</a> and <a href="#tut-datafile">easy to combine eRuby template with YAML datafile</a> +<li>Context object available and easy to combine eRuby template with YAML datafile </li> -<li><a href="#printenabled-enhancer">Print statement available</a> +<li>Print statement available </li> -<li><a href="#enhancer">Easy to expand and customize in subclass</a> +<li>Easy to expand and customize in subclass </li> -<li><a href="#topics-rails">Ruby on Rails support</a> +<li><a href="#rails">Ruby on Rails support</a> </li> -<li><a href="#topcs-modruby">mod_ruby support</a> +<li>mod_ruby support|#topcs-modruby </li> </ul> <p>Erubis is implemented in pure Ruby. It requires Ruby 1.8 or higher. @@ -139,6 +139,16 @@ It has the following features. </li> </ul> </li> + <li><a href="#rails">Ruby on Rails Support</a> + <ul> + <li><a href="#rails-settings">Settings</a> + </li> + <li><a href="#rails-preprocessing">Preprosessing</a> + </li> + <li><a href="#rails-others">Others</a> + </li> + </ul> + </li> <li><a href="#topics">Other Topics</a> <ul> <li><a href="#topics-fasteruby">Class Erubis::FastEruby</a> @@ -149,8 +159,6 @@ It has the following features. </li> <li><a href="#topics-tinyeruby">Erubis::TinyEruby class</a> </li> - <li><a href="#topics-rails">Ruby on Rails Support</a> - </li> <li><a href="#topics-php">NoTextEnhancer and NoCodeEnhancer in PHP</a> </li> <li><a href="#topcs-modruby">Helper Class for mod_ruby</a> @@ -2281,6 +2289,176 @@ document.write(_buf.join("")); <br> +<a name="rails"></a> +<h2 class="section1">Ruby on Rails Support</h2> +<p>Erubis supports Ruby on Rails. +This section describes how to use Erubis with Ruby on Rails. +</p> +<a name="rails-settings"></a> +<h3 class="section2">Settings</h3> +<ol type="1"> +<li>Add the following code to your 'config/environment.rb'. +<div class="program_caption"> +config/environment.rb</div> +<pre class="program">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 +</pre> +<p> This will replace ERB in Rails by Erubis entirely. +</p> +</li> +<li>(Optional) apply the following patch to 'action_pack/lib/action_view/base.rb'. +<div class="program_caption"> +action_view_base_rb.patch</div> +<pre class="program">--- 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] ||= {} +</pre> +<p> This patch is included in erubis_2.X.X/contrib directory and the following is an + example to apply this patch. +</p> +<div class="terminal_caption"> +how to apply patch:</div> +<pre class="terminal">$ 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 +</pre> +<p> Notice that this patch is not necessary if you are using Ruby on Rails ver 1.1 or 1.2, but it is recommended. +</p> +</li> +<li>Restart web server. +<pre class="terminal">$ ruby script/server +</pre> +</li> +</ol> +<p>The setting is above all. +</p> +<br> + + +<a name="rails-preprocessing"></a> +<h3 class="section2">Preprosessing</h3> +<p><strong>(Experimental)</strong> +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. +</p> +<p>For example, assume the following template. +This is slow because link_to() method is called every time when template is rendered. +</p> +<pre class="program"><%= link_to 'Create', :action=>'create' %> +</pre> +<p>The following is faster than the above, but not flexible because url is fixed. +</p> +<pre class="program"><a href="/users/create">Create</a> +</pre> +<p>Preprocessing solves this problem. +If you use '[%= %]' instead of '<%= %>', preprocessor evaluate it only once when template is loaded. +</p> +<pre class="program"><strong>[%= link_to 'Create', :action=>'create'%]</strong> +</pre> +<p>The above is evaluated by preprocessor and replaced to the following code automatically. +</p> +<pre class="program"><a href="/users/create">Create</a> +</pre> +<p>Notice that this is done only once when template file is loaded. +It means that link_to() method is not called when template is rendered. +</p> +<p>If link_to() method have variable arguments, use <code>_?()</code> helper method. +</p> +<pre class="program"><% for use in @users %> +[%= link_to <strong>_?('user.name')</strong>, :action=>'show', :id=><strong>_?('user.id')</strong> %] +<% end %> +</pre> +<p>The above is evaluated by preprocessor when template is loaded and expanded into the following code. +This will be much faster because link_to() method is not called when rendering. +</p> +<pre class="program"><% for user in @users %> +<a href="/users/show/<strong><%=user.id%></strong>"><strong><%=user.name%></strong></a> +<% end %> +</pre> +<p>Preprocessing statement (<code>[% %]</code>) is also available as well as preprocessing expression (<code>[%= %]</code>). +</p> +<pre class="program"><select name="state"> + <option value="">-</option> +<strong>[% for code in states.keys.sort %]</strong> + <option value="<strong>[%= code %]</strong>"><strong>[%= states[code] %]</strong></option> +<strong>[% end %]</strong> +</select> +</pre> +<p>The above will be evaluated by preprocessor and expanded into the following when template is loaded. +In the result, rendering speed will be much faster because for-loop is not executed when rendering. +</p> +<pre class="program"><select name="state"> + <option value="">-</option> + <option value="AK">Alaska</option> + <option value="AL">Alabama</option> + <option value="AR">Arkansas</option> + <option value="AS">American Samoa</option> + <option value="AZ">Arizona</option> + <option value="CA">California</option> + <option value="CO">Colorado</option> + .... +</select> +</pre> +<p>Notice that it is not recommended to use preprocessing with tag helpers, +because tag helpers generate different html code when form parameter has errors or not. +</p> +<p>Helper methods of Ruby on Rails are divided into two groups. +</p> +<ul type="disc"> +<li>link_to() or _() (method of gettext package) are not need to call for every time + as template is rendered because it returns same value when same arguments are passed. + These methods can be got faster by preprocessing. +</li> +<li>Tag helper methods should be called for every time as template is rendered + because it may return differrent value even if the same arguments are passed. + Preprocessing is not available with these methods. +</li> +</ul> +<br> + + +<a name="rails-others"></a> +<h3 class="section2">Others</h3> +<ul type="disc"> +<li>ActionView::Helpers::CaptureHelper#capture() and ActionView::Helpers::Texthelper#concat() are available. +</li> +</ul> +<ul type="disc"> +<li>If Erubis::Helper::Rails.show_src is ture, Erubis prints converted Ruby code into log file (ex. 'log/development.log'). +</li> +</ul> +<p>If it is nil (default), Erubis prints converted Ruby code into log file only when development mode. + It is useful for debugging. +</p> +<br> + + +<br> + + <a name="topics"></a> <h2 class="section1">Other Topics</h2> <a name="topics-fasteruby"></a> @@ -2412,73 +2590,6 @@ try Erubis::TinyEruby class. <br> -<a name="topics-rails"></a> -<h3 class="section2">Ruby on Rails Support</h3> -<p>Erubis supports Ruby on Rails. -</p> -<ol type="1"> -<li>Add the following code to your 'config/environment.rb'. -<div class="program_caption"> -config/environment.rb</div> -<pre class="program">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 -</pre> -<p> This will replace ERB in Rails by Erubis entirely. -</p> -</li> -<li>(Optional) apply the following patch to 'action_pack/lib/action_view/base.rb'. -<div class="program_caption"> -action_view_base_rb.patch</div> -<pre class="program">--- 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] ||= {} -</pre> -<p> This patch is included in erubis_2.X.X/contrib directory and the following is an - example to apply this patch. -</p> -<div class="terminal_caption"> -how to apply patch:</div> -<pre class="terminal">$ 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 -</pre> -<p> Notice that this patch is not necessary if you are using Ruby on Rails ver 1.1 or 1.2, but it is recommended. -</p> -</li> -<li>Restart web server. -<pre class="terminal">$ ruby script/server -</pre> -</li> -</ol> -<p>ActionView::Helpers::CaptureHelper#capture() and ActionView::Helpers::Texthelper#concat() are available. -</p> -<p>If Erubis::Helper::Rails.show_src is ture, Erubis prints converted Ruby code into log file (ex. 'log/development.log'). -It is useful for debugging. -</p> -<br> - - <a name="topics-php"></a> <h3 class="section2">NoTextEnhancer and NoCodeEnhancer in PHP</h3> <p>NoTextEnhancer and NoCodEnahncer are quite useful not only for eRuby but also for PHP. @@ -2618,7 +2729,7 @@ $ sudo chmod 775 . </ol> <p>You must set your directories to be writable by web server process, because Apache::ErubisRun calls Erubis::Eruby.load_file() internally which creates cache files -in the same directory as '*.rhtml' file. +in the same directory in which '*.rhtml' file exists. </p> <br> |