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

You can provide options to the plugin method:

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

The following options are supported:

:cache

nil/false to not cache templates (useful for development), defaults to true unless RACK_ENV is development to automatically use the default template cache.

:engine

The tilt engine to use for rendering, defaults to ‘erb’.

:escape

Use Roda’s Erubis escaping support, which makes <%= %> escape output, <%== %> not escape output, and handles postfix conditions inside <%= %> tags.

:ext

The file extension to assume for view files, defaults to the :engine option.

:layout

The base name of the layout file, defaults to ‘layout’.

:layout_opts

The options to use when rendering the layout, if different from the default options.

:template_opts

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

:views

The directory holding the view files, defaults to ‘views’ in the current directory.

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

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

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

: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 :ext option in combination with the template name.

: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.

:template_class

Provides the template class to use, inside of using Tilt or a Tilt.

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 :inline or :path as one of the keys.

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.



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/roda/plugins/render.rb', line 87

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

  if opts[:opts] && !opts[:template_opts]
    RodaPlugins.deprecate("The render plugin :opts option is deprecated and will be removed in Roda 2.  Switch to using the :template_opts option")
    app.opts[:render][:template_opts] = opts[:opts]
  end

  opts = app.opts[:render]
  opts[:engine] ||= "erb"
  opts[:ext] = nil unless opts.has_key?(:ext)
  opts[:views] ||= File.expand_path("views", Dir.pwd)
  opts[:layout] = "layout" unless opts.has_key?(:layout)
  opts[:layout_opts] ||= (opts[:layout_opts] || {}).dup

  if layout = opts[:layout]
    layout = {:template=>layout} unless layout.is_a?(Hash)
    opts[:layout_opts] = opts[:layout_opts].merge(layout)
  end

  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]
    template_opts[:engine_class] = ErubisEscaping::Eruby
  end
  opts[:cache] = app.thread_safe_cache if opts.fetch(:cache, ENV['RACK_ENV'] != 'development')
  opts.extend(RodaDeprecateMutation)
  opts[:layout_opts].extend(RodaDeprecateMutation)
  opts[:template_opts].extend(RodaDeprecateMutation)
end

.load_dependencies(app, opts = OPTS) ⇒ Object 



80
81
82
83
84
 
# File 'lib/roda/plugins/render.rb', line 80

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