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. Attempts to render paths outside of this directory will raise an error. Defaults to the
:views
directory. - :cache
-
nil/false to disable template caching by default. By default, caching is disabled by default if RACK_ENV is development.
- :cache_class
-
A class to use as the template cache instead of the default.
- :check_paths
-
Can be set to false to turn off template path checking.
- :engine
-
The tilt engine to use for rendering, also the default file extension for templates, defaults to ‘erb’.
- :escape
-
Use Erubi as the ERB template engine, and enable escaping by default, which makes
<%= %>
escape output and<%== %>
not escape output. - :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.
- :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 an example of using these options:
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:
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
Class Method Summary collapse
-
.configure(app, opts = OPTS) ⇒ Object
Setup default rendering options.
Class Method Details
.configure(app, opts = OPTS) ⇒ Object
Setup default rendering options. See Render for details.
136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 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 |
# File 'lib/roda/plugins/render.rb', line 136 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] || "erb").dup.freeze opts[:views] = app.(opts[:views]||"views").freeze opts[:allowed_paths] ||= [opts[:views]].freeze opts[:allowed_paths] = opts[:allowed_paths].map{|f| app.(f, nil)}.uniq.freeze opts[:check_paths] = true unless opts.has_key?(:check_paths) unless opts.has_key?(:explicit_cache) opts[:explicit_cache] = if opts.fetch(:cache, true) ENV['RACK_ENV'] == 'development' else true end end opts[:cache] = orig_cache || (opts[:cache_class] || RodaCache).new opts[:layout_opts] = (opts[:layout_opts] || {}).dup opts[:layout_opts][:_is_layout] = true if opts[:layout_opts][:views] opts[:layout_opts][:views] = app.(opts[:layout_opts][:views]).freeze 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' unless template_opts.has_key?(:default_encoding) template_opts[:default_encoding] = Encoding.default_external end if opts[:escape] require 'tilt/erubi' template_opts[:escape] = true 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 |