Page layouts

1 What are page layouts?

Every page in Alchemy has a page layout.

Think of page layouts as types of pages with different settings and markup. They are used to define page abilities like available elements or cells, caching settings, enabling xml feeds, and so on.

Page layouts are defined in the config/alchemy/page_layouts.yml file.

1.1 How do they work?

When creating a new page the user gets prompted to select a page layout. Depending on its settings (page_layouts.yml) the user has certain elements to manage content with.

1.2 Rendering

Beside the page layout definitions in the page_layouts.yml file, they all have a Rails view partial which is yielded on the Rails layout (for example on app/views/layouts/application.html.erb).

They are being parsed through a template engine (ERB, haml or slim) so you can write HTML/CSS and execute Ruby code there.

You can find all page layout partials in the app/views/alchemy/page_layouts folder.

They are named after the page layout’s name you defined in the page_layouts.yml file.

If no page layout partial is found, the _standard.html.erb file gets rendered.

Alchemy comes with a generator that creates the partials for you.
Run rails g alchemy:page_layouts --skip inside you terminal.

1.3 Caching

If using the global caching option (defined in config/alchemy/config.yml) which is enabled by default, your page layouts will be cached for fast delivering through Rails action caching.

You can disable caching of certain pages in the page_layouts.yml file by using the cache: false setting.

2 Create page layouts

Follow this guide to learn how to create page layouts which can be chosen by the user when creating a new page.

2.1 Defining page layouts

In order to create page layouts you have to edit the file config/alchemy/page_layouts.yml.

Generate Alchemy’s files and folders with rails g alchemy:scaffold

2.2 Configuration options

Every page layout needs at least a name. You don’t need to set every option. It depends on what you need for pages with that layout type.

  • name: [String]
    The name of the layout used for views and inside the database. You can render a layout with the render_page_layout(name) helper.
  • elements: [Array]
    A list of element names that can be placed on this layout i.e. [text, picture].
    Elements are defined inside the elements.yml file.
  • autogenerate: [Array]
    A list of element names that are autogenerated after creating a Page of that type.
  • unique: [Boolean]
    (Default false) Pass true and the user can only choose this layout once inside a language tree.
  • cache: [Boolean]
    (Default true) Pass false to disable the caching for this kind of pages. Recommended for contact forms and such likes.
2.2.2 Additional/advanced options
  • layoutpage: [Boolean]
    Layout pages (or global pages) are outside the normal page tree and can be used to place “global” Elements like footers and sidebars.
  • hide: [Boolean]
    Pass true to hide this layout from the user.
  • searchresults: [Boolean]
    Pass true to use this type of page for rendering the search results of the build in fulltext search.
  • feed: [Boolean]
    Pass true to enable a RSS feed of news elements from this page.
  • redirects_to_external: [Boolean]
    Pass true to disable normal page rendering and redirect to a external page instead.
  • taggable: [Boolean]
    Pass true to be able to assign tags within page settings.
  • controller: [String]
    Controller to use instead of the default Alchemy::PagesController
  • action: [String]
    Controllers action to use instead of the default Alchemy::PagesController#show

2.3 Example

Lets say you want to create a contact page with a headline element, an e-mail formular and a text element on it.

This page should be unique, because you don’t want to give your content manager the possibility to create more than one contact form.

This page must not be cached, because of validation messages and user specific form content.

We also want to autogenerate the headline and the contactform element after the page gets created.


# config/alchemy/page_layouts.yml
- name: contact
  cache: false
  unique: true
  elements: [headline, contactform, text]
  autogenerate: [headline, contactform]

Please ensure to restart the server after editing page_layouts.yml.

2.4 Generate the views

Every page layout defined in the page_layouts.yml file should have a view partial located in app/views/alchemy/page_layouts/.

There is no need to create these partials manually. Alchemy CMS comes with a Rails generator task which creates these partials for you.

So after defining the page layouts, you can generate all the corresponding partials for them.

rails g alchemy:page_layouts --skip

Using the example above, which defines a contact layout, the generator will create a partial named _contact.html.erb.

You can pass --template-engine or -e as option to use one of haml, slim and erb. The default is depending on your default template engine in your Rails host app.

3 Customize the views

Alchemy does not place any HTML markup in your generated page layouts partial.

So:


<%= render_elements %>

is all you will see. Feel free to customize the HTML so it fits your needs.

Alchemy comes with tons of view helpers that you can use to render elements.
Please have a look into the ElementsHelper documentation

3.1 Translate page layout names

Page layout names are passed through the I18n library. You can translate them in your Alchemy locale files.

3.1.1 Example

# config/locales/alchemy.de.yml
de:
  alchemy:
    page_layout_names:
      contact: Kontakt
      search: Suche

All translation keys used by Alchemy are scoped under the alchemy namespace.