Ruby Objects in Templates

You can call functions on three objects in templates – @site, @page, and @fragment. All of these objects have fields accessible using the routines listed below under the (as they inherit from that object). All of three objects above inherit from the FieldHelper object listed below.

@site

This is the site object, which contains keys matching those found in the site.info file

@page

The current page object – you can call routines in this without prefixing your calls with @page – it is the default context for calls. Contains keys matching those from the page.info file for the current page.

@fragment

The current fragment object. This is only valid in fragment templates, as in other templates there is no current fragment.

Available Ruby Methods in templates

You can see all the available methods in the three objects above, along with their source on the objects page. Below are a few of those you might come across more frequently in templates :

Remember when calling methods, you must use the eruby syntax, which means always prefix your call with <= and end it with %>. You should omit the ’=’ if you don’t want to print the result, but most of the time you want <= code() %> so that the result ends up in the HTML page (contrast calls to field() and field?() below to see the difference).

Also remember that when calling @page is the default context, so methods of @page can be called without the @page prefix (like breadcrumbs below)

Page Methods

breadcrumbs

Output the breadcrumbs for this particular page

e.g. Home > Site Structure > Style > Templates

<%= breadcrumbs %>

navigation(options = {})

Output a navigation list of links to pages under a certain page

Defaults to a full list of pages under root – options can be supplied. See Objects page for more details.

<%= navigation(:parent_page => 'root') %>

stylesheet_link_tag, javascript_link_tag

Output stylesheet or javascript link tags for the page header

You can add options at the end (optionally) – assumes location of stylesheets and javascripts to be in folders at root level of website.

<%= stylesheet_link_tag('universal','structure') %>

render(options = {})

Output a navigation list of links to pages under a certain page

Used to render either a list of pages, fragment or collection of fragments. This routine is called by navigation to produce the navigation and also by pages themselves to render their fragments in templates. Valid options :

• :partial => which template to use?
• :fragment => render a fragment
• :page_fragments => render all the fragments from a page
• :page_list => render a list of all child pages
• :include_root => if true show root of page list in list (false by default)
• :exclude => which fragments to exlude from a list
• :related => if true show only pages related to current page (false by default)
• :depth => the depth at which to render a list of child pages
• :order => The field to set sort order on
• :reverse => Should we reverse sort order (false by default)

<%= render(:page_list => 'style', :order => 'date', :reverse => true) %>

Or a more complex example which generates navigation similar to the navigation shortcut:

<%= render(:page_list => 'root', :depth => 0, :order => 'order', :include_root => true, :related => true) %>

Fragment Methods

iso_date

Output the formatted date for this fragment

<%= @fragment.date %>

iso_date

Output the ISO formatted date for this fragment

<%= @fragment.iso_date %>

text_html_summary(max_chars)

Output a summary with max_chars length wrapped in html

<%= @fragment.text_html_summary(200) %>

text_summary(max_chars)

Output a summary with max_chars length

<%= @fragment.text_summary(399) %>

image_html

Output HTML for the fragment image (if there is one)

Returns a blank string if no image

<%= @fragment.image_html %>

preview_image_html

Output HTML for the fragment preview image

<%= @fragment.preview_image_html %>

Page, Site and Fragment Methods

field(in_name)

Get the text for a field (after substitutions with Textile and eruby)

Returns a blank string if nothing found

<%= @page.field('title') %>

field?(in_name)

Check that a field exists

<% @page.field?('title') %>