bhanditz / europeana-styleguide-ruby

Europeana styleguide templates for Rails applications

Europeana::Styleguide

Europeana::Styleguide contains Mustache templates for a consistent front-end design across Europeana's Ruby on Rails web applications.

Templates in this repository are automatically updated from commits to Europeana-Patternlab's source/_patterns directory.

Installation

Add these lines to your application's Gemfile:

gem 'europeana-styleguide', github: 'europeana/europeana-styleguide-ruby'
gem 'europeana-i18n', github: 'europeana/europeana-i18n-ruby'
gem 'stache', github: 'europeana/stache', branch: 'europeana-styleguide' # until upstream merges our pull requests

And then execute:

$ bundle

Configuration

Asset host

You will need to set the environment variable EUROPEANA_STYLEGUIDE_ASSET_HOST to the base URL where the styleguide assets are to be served from.

Caching

In a production environment, it is strongly recommended that you enable the caching of compiled templates.

Without this, the Mustache templates are compiled into ERB every time that they are needed, which is a resource intensive process.

To enable template caching, create an initializer in your Rails app:

# config/initializers/stache.rb
Stache.configure do |c|
  # Store compiled templates in memory
  c.template_cache = ActiveSupport::Cache::MemoryStore.new
end

Usage

Controllers

The gem's Mustache templates are in its app/views directory. To make these available as views in your application, include the module Europeana::Styleguide in the relevant controller:

class StyledController < ApplicationController
  include Europeana::Styleguide
end

Include the module in ApplicationController to make the styleguide templates available to all controllers.

View templates

Styleguide templates do not following Rails's view naming conventions. You will need to:

1. Create a view template in your app/views directory named after the controller action, as usual
2. In that view template, include the page-specific styleguide template, along with the styleguide header and footer

See "complete example", below, for a demonstration.

Customising templates

Individual Mustache templates can be overriden locally by creating a file of the same name in your application's app/views directory. For example, to override the gem's app/views/templates/Search/Search-results-list.mustache template, copy it to $RAILS_ROOT/app/views/templates/Search/Search-results-list.mustache and edit as required.

Updating templates

If you also have the Europeana-Patternlab repository cloned and want to use it to populate view templates and other assets in your clone of europeana-styleguide-ruby, for instance to test a feature branch of the PatternLab repository, use the supplied Rake task:

bundle exec rake europeana_styleguide:populate[../Europeana-Patternlab]

... assuming that the cloned PatternLab repository is in the directory ../Europeana-Patternab.

View classes

Data is supplied to the Mustache templates for variable placeholder expansion via Stache view classes named after the controller action, and stored under app/views alongside the Mustache templates. These view classes should sub-class Europeana::Styleguide::View.

For example, given a controller action SearchController#index, with a view template app/views/search/index.html.mustache, provide data to it via a view class named Search::Index.

Any public methods of a view class will be available for the expansion of variable placeholders in the Mustache template. All such methods must be parameterless. For example:

app/views/search/index.html.mustache:

<p>{{result_count}}</p>

app/views/templates/search/search_results_list.rb:

module Search
  class Index < Europeana::Styleguide::View
    def result_count
      @response.total
    end
  end
end

View classes will have access to any instance variables set on your controller, and any view helper methods.

To support nested variable placeholders separated by ".", have your methods return a Ruby Hash with keys like the placeholder's sub-keys, or an object responding to methods like the placeholder's sub-keys.

Layouts

Rails layouts will not work, because expansion of variable placeholders from the Mustache templates is not performed within the layout.

I18n

Europeana::Styleguide contains a helper to allow you to perform Rails i18n lookups from within Mustache templates. Prefix a variable placeholder in the template with "i18n." and its expansion will be translated from the application's available locales.

app/views/welcome/index.html.mustache:

<p>{{i18n.welcome.index.hello}}</p>

config/locales/en.yml:

en:
  welcome:
    index:
      hello: Hello World

Complete example

Controller

app/controllers/search_controller.rb:

class SearchController < ApplicationController
  include Europeana::Styleguide

  def index
    # search logic
    @results = ['result 1', 'result 2']
  end
end

View class

app/views/search/index.rb:

module Search
  class Index < Europeana::Styleguide::View
    def page_title
      t('search.index.page_title')
    end

    def result_count
      @results.size
    end
  end
end

View template

app/views/search/index.html.mustache:

{{>atoms/meta/_head}}
{{>templates/Search/Search-results-list}}
{{>atoms/meta/_foot}}