Skip to content

templating.md

Latest commit

 

History

History
180 lines (127 loc) · 4.91 KB

templating.md

File metadata and controls

180 lines (127 loc) · 4.91 KB

Templating

Directories

Before we get started, it's good to know that there are a couple of "special" folders within any Roger project. Don't worry, you can configure these; they're not hard-coded. The folders are:

  • project-path this is the main directory containing the Rogerfile and all other directories.
  • html-path this is the directory where all your HTML/CSS/Javascript will go (in subdirectories of course).
  • partials-path this is the directory where all partials reside.
  • layouts-path this is the directory where the layouts hang out.

The default project tree looks like this:

project-path
  |
  |- html (html-path)
  |
  |- partials (partials-path)
  |
  \- layouts (layouts-path)

Only the html-path has to exist. The others are not required.

HTML

The html-path is actually the root for all you front-end code. This is what will be served as the document-root with roger serve and will be the base for a release when using roger release.

In the html-path you can put static files (images, documents, etc.) but also templates. Anything that the Tilt Engine can handle is ok. The only thing Roger adds is handling for front-matter, layouts and partials.

Front-matter

Every template can optionally start with a bit of front-matter. Front-matter is defined as follows:

---
key: value
---

Front-matter is parsed as YAML and can contain data to be used in the template, layout or partial. You can access these values in the templates (layouts and partials included) by using document.KEY.

Layouts

Layouts are basically "wrap" templates. The layout will wrap around the rendered template. In the template front-matter you define what layout it should use by setting the layout key. See the example below.

Basic layout example

html/template.html.erb

---
layout: default
---
Template

layouts/default.html.erb

Layout (before)
<% yield %>
Layout (after)

Results

This would result in:

Layout (before)
Template
Layout (after)

Default layout

It is possible to define a global default layout per template extension in the Rogerfile.

roger.project.options[:renderer][:layout] = {
  "html.erb" => "my_default_layout",
  "md.erb" => "my_markdown_layout",
  "md" => "my_markdown_layout"
}

The layout can of course be overwritten in the frontmatter. Setting an empty layout will disable the default layout.

Advanced layouts

Using content_for

You can have multiple regions in your layout. That way you can yield multiple times for each region. See the example below for usage on content_for :name do ... end and yield :name.

content_for example
html/template.html.erb
---
layout: default
---

<% content_for :sidebar %>
  Sidebar
<% end %>

The is the rest of the content
layouts/default.html.erb
<% yield %>

<div class="sidebar">
  <% yield :sidebar %>
</div>
Result
The is the rest of the content 

<div class="sidebar">
  Sidebar
</div>

Partials

Partials are little pieces of template that can be easily reused. You can access the partials throught the partial("partialpath") method. The renderer will search for partials:

  • relative to the template currently being rendered with partialpath being prefixed with and underscore (so: _partialpath).
  • relative to the partial path that has been set up.

You can optionally pass variables to the partial by passing a ruby hash of options as a second parameter. This works like this:

partial("path/to/partial/relative/to/partials-path", {:key => "value"})

In the partial these can be accessed as local variables. So for instance in you test.html.erb partial that would look like this:

<%= key %>

Blocks

Just like content_for partials also accept block syntax. This way you can pass a block of HTML to the partial. It works like this:

<% partial "my-partial" do %>
  Pass it to the partial
<% end %>

Within your partial file you can then use the content by yielding it:

<div class="my-partial">
    <% yield %>
</div>

Helpers

Template helpers allow you to have custom functions in your templates. These functions will be executed in the same context as the template is in. This means they will have access to all other template features like the document and env variables.

A helper is nothing more than a plain old Ruby module containing a bunch of functions.

Registering helpers

Registering helpers can best be done in the Rogerfile. Register this module as following:

Roger::Renderer.helper MyHelperModule

After registration the helpers are available for use in all templates, partials, layouts, etc. See the template helpers tests for example usage.

Access to Project

You can access the Roger project with all it's might and glory by accessing env["roger.project"].