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
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.
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
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
They are named after the page layout’s name you defined in the
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.
rails g alchemy:page_layouts --skip inside you terminal.
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
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.
2.2.1 Recommended options
The name of the layout used for views and inside the database. You can render a layout with the
A list of element names that can be placed on this layout i.e.
Elements are defined inside the
A list of element names that are autogenerated after creating a Page of that type.
(Default false) Pass
trueand the user can only choose this layout once inside a language tree.
(Default true) Pass
falseto disable the caching for this kind of pages. Recommended for contact forms and such likes.
2.2.2 Additional/advanced options
Layout pages (or global pages) are outside the normal page tree and can be used to place “global” Elements like footers and sidebars.
Pass true to hide this layout from the user.
Pass true to use this type of page for rendering the search results of the build in fulltext search.
Pass true to enable a RSS feed of news elements from this page.
Pass true to disable normal page rendering and redirect to a external page instead.
Pass true to be able to assign tags within page settings.
Controller to use instead of the default Alchemy::PagesController
Controllers action to use instead of the default Alchemy::PagesController#show
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
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
You can pass
-e as option to use one of
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.
<%= 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.
# config/locales/alchemy.de.yml de: alchemy: page_layout_names: contact: Kontakt search: Suche
All translation keys used by Alchemy are scoped under the