Module: Roda::RodaPlugins::Render

Defined in:
lib/roda/plugins/render.rb

Overview

The render plugin adds support for template rendering using the tilt library. Two methods are provided for template rendering, view (which uses the layout) and render (which does not).

plugin :render

route do |r|
  r.is 'foo' do
    view('foo') # renders views/foo.erb inside views/layout.erb
  end

  r.is 'bar' do
    render('bar') # renders views/bar.erb
  end
end

The render and view methods just return strings, they do not have side effects (unless the templates themselves have side effects). As Roda uses the routing block return value as the body of the response, in most cases you will call these methods as the last expression in a routing block # to have the response body be the result of the template rendering.

Because render and view just return strings, you can call them inside templates (i.e. for subtemplates/partials), or multiple times in the same route and combine the results together:

route do |r|
  r.is 'foo-bars' do
    @bars = Bar.where(:foo).map{|b| render(:bar, :locals=>{:bar=>b})}.join
    view('foo')
  end
end

You can provide options to the plugin method:

plugin :render, :engine=>'haml', :views=>'admin_views'

Plugin Options

The following plugin options are supported:

:allowed_paths

Set the template paths to allow if :check_paths is true. Defaults to the :views directory.

:cache

nil/false to disallow template caching completely.

:cache_class

A class to use as the template cache instead of the default.

:check_paths

Check template paths start with one of the entries in :allowed_paths, and raise a RodaError if the path doesn’t.

:engine

The tilt engine to use for rendering, also the default file extension for templates, defaults to ‘erb’.

:escape

Use Roda’s Erubis escaping support, which makes <%= %> escape output, <%== %> not escape output, and handles postfix conditions inside <%= %> tags. Can have a value of :erubi to use Erubi escaping support.

:escape_safe_classes

String subclasses that should not be HTML escaped when used in <%= %> tags, when :escape=>true is used. Can be an array for multiple classes.

:escaper

Object used for escaping output of <%= %>, when :escape=>true is used, overriding the default. If given, object should respond to escape_xml with a single argument and return an output string.

:explicit_cache

Only use the template cache if the :cache option is provided when rendering (useful for development). Defaults to true if RACK_ENV is development, allowing explicit caching of specific templates, but not caching by default.

:inherit_cache

Whether to create a dup of the cache in subclasses. The default is false, which starts subclasses with an empty cache.

:layout

The base name of the layout file, defaults to ‘layout’. This can be provided as a hash with the :template or :inline options.

:layout_opts

The options to use when rendering the layout, if different from the default options. To pass local variables to the layout, include a :locals option inside :layout_opts. To automatically merge the view template locals into the layout template locals, include a :merge_locals option inside :layout_opts.

:template_opts

The tilt options used when rendering all templates. defaults to: {:outvar=>'@_out_buf', :default_encoding=>Encoding.default_external}.

:engine_opts

The tilt options to use per template engine. Keys are engine strings, values are hashes of template options.

:views

The directory holding the view files, defaults to the ‘views’ subdirectory of the application’s :root option (the process’s working directory by default).

Render/View Method Options

Most of these options can be overridden at runtime by passing options to the view or render methods:

view('foo', :engine=>'html.erb')
render('foo', :views=>'admin_views')

There are additional options to view and render that are available at runtime:

:cache

Set to false to not cache this template, even when caching is on by default. Set to true to force caching for this template, even when the default is to not cache (e.g. when using the :template_block option).

:cache_key

Explicitly set the hash key to use when caching.

:content

Only respected by view, provides the content to render inside the layout, instead of rendering a template to get the content.

:inline

Use the value given as the template code, instead of looking for template code in a file.

:locals

Hash of local variables to make available inside the template.

:path

Use the value given as the full pathname for the file, instead of using the :views and :engine option in combination with the template name.

:scope

The object in which context to evaluate the template. By default, this is the Roda instance.

:template

Provides the name of the template to use. This allows you pass a single options hash to the render/view method, while still allowing you to specify the template name.

:template_block

Pass this block when creating the underlying template, ignored when using :inline. Disables caching of the template by default.

:template_class

Provides the template class to use, inside of using Tilt or Tilt[:engine].

Here’s how those options are used:

view(:inline=>'<%= @foo %>')
render(:path=>'/path/to/template.erb')

If you pass a hash as the first argument to view or render, it should have either :template, :inline, :path, or :content (for view) as one of the keys.

Speeding Up Template Rendering

By default, determining the cache key to use for the template can be a lot of work. If you specify the :cache_key option, you can save Roda from having to do that work, which will make your application faster. However, if you do this, you need to make sure you choose a correct key.

If your application uses a unique template per path, in that the same path never uses more than one template, you can use the view_options plugin and do:

set_view_options :cache_key=>r.path_info

at the top of your route block. You can even do this if you do have paths that use more than one template, as long as you specify :cache_key specifically when rendering in those paths.

If you use a single layout in your application, you can also make layout rendering faster by specifying :cache_key inside the :layout_opts plugin option.

Defined Under Namespace

Modules: ClassMethods, InstanceMethods

Constant Summary collapse

OPTS = 
{}.freeze

Class Method Summary collapse

Class Method Details

.configure(app, opts = OPTS) ⇒ Object

Setup default rendering options. See Render for details.



158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/roda/plugins/render.rb', line 158

def self.configure(app, opts=OPTS)
  if app.opts[:render]
    orig_cache = app.opts[:render][:cache]
    opts = app.opts[:render][:orig_opts].merge(opts)
  end
  app.opts[:render] = opts.dup
  app.opts[:render][:orig_opts] = opts

  opts = app.opts[:render]
  opts[:engine] = (opts[:engine] || opts[:ext] || "erb").dup.freeze
  opts[:views] = app.expand_path(opts[:views]||"views").freeze
  opts[:allowed_paths] ||= [opts[:views]].freeze
  opts[:allowed_paths] = opts[:allowed_paths].map{|f| app.expand_path(f, nil)}.uniq.freeze

  if opts.fetch(:cache, true)
    if orig_cache
      opts[:cache] = orig_cache
    elsif cache_class = opts[:cache_class]
      opts[:cache] = cache_class.new
    else
      opts[:cache] = app.thread_safe_cache
    end
  end

  opts[:explicit_cache] = ENV['RACK_ENV'] == 'development' unless opts.has_key?(:explicit_cache)

  opts[:layout_opts] = (opts[:layout_opts] || {}).dup
  opts[:layout_opts][:_is_layout] = true

  if opts[:layout_opts][:merge_locals] && opts[:locals]
    opts[:layout_opts][:locals] = opts[:locals].merge(opts[:layout_opts][:locals] || {})
  end

  if layout = opts.fetch(:layout, true)
    opts[:layout] = true unless opts.has_key?(:layout)

    case layout
    when Hash
      opts[:layout_opts].merge!(layout)
    when true
      opts[:layout_opts][:template] ||= 'layout'
    else
      opts[:layout_opts][:template] = layout
    end
  end
  opts[:layout_opts].freeze

  template_opts = opts[:template_opts] = (opts[:template_opts] || {}).dup
  template_opts[:outvar] ||= '@_out_buf'
  if RUBY_VERSION >= "1.9" && !template_opts.has_key?(:default_encoding)
    template_opts[:default_encoding] = Encoding.default_external
  end
  if opts[:escape] == :erubi
    require 'tilt/erubi'
    template_opts[:escape] = true
  elsif opts[:escape]
    template_opts[:engine_class] = ErubisEscaping::Eruby

    opts[:escaper] ||= if opts[:escape_safe_classes]
      ErubisEscaping::UnsafeClassEscaper.new(opts[:escape_safe_classes])
    else
      ::Erubis::XmlHelper
    end
  end
  template_opts.freeze

  engine_opts = opts[:engine_opts] = (opts[:engine_opts] || {}).dup
  engine_opts.to_a.each do |k,v|
    engine_opts[k] = v.dup.freeze
  end
  engine_opts.freeze

  opts.freeze
end

.load_dependencies(app, opts = OPTS) ⇒ Object 



151
152
153
154
155
 
# File 'lib/roda/plugins/render.rb', line 151

def self.load_dependencies(app, opts=OPTS)
  if opts[:escape] && opts[:escape] != :erubi
    app.plugin :_erubis_escaping
  end
end