Layouts

Develop the layouts that pages on your Live Editor site will be based on.

In a Live Editor theme, layouts are where everything starts: every page on a Live Editor site must be based on a layout.

A Live Editor theme may have 1 or more layouts. You’ll typically need to create a different layout for each major “type” of page on your site. For example, you may need to create layouts named Home, Product, Landing Page, and Interior.

One of the major tasks in creating a layout is to define editable regions. Regions are pre-defined containers in which page authors will add content. Page authors will only be able to add content to these pre-defined regions and won’t be able to edit any other part of the page. This allows you as the HTML expert to keep the site’s structure and appearance in order.

Default layout

If you generate a brand new theme using Live Editor CLI:

liveeditor new my_theme

You will see a new set of files and folders, including a folder called layouts.

my_theme
- ...
- layouts
  - site_layout.liquid
  - layouts.json
- ...

Within the layouts folder are 2 files of interest: layouts.json and site_layout.liquid.

Configuring layouts with `layouts.json`

The layouts.json file uses JSON markup. Its job is to list the layouts within the theme and any configuration options for the layouts and their editable regions.

If you omit the configuration for a layout from layouts.json, Live Editor will apply default values for all of the configuration options afforded by layouts.json.

The example layouts.json will look something like this:

layouts.json

        {
          "layouts": [
            "title": "Site",
            "description": "Global layout for all pages in the site.",
            "regions": [
              {
                "title": "Main"
              }
            ]
          ]
        }

The layouts.json file describes the following:

One configured layout with a title of “Site.”
The description of the layout in the admin interface will be “Global layout for all pages in the site.”
The Site layout has 1 region named “Main.”

Here are the options available at the layout level:

Option	Required	Description
`title`	Yes	`string` Titleized version of the layout’s `.liquid` file. For example, if there were a file at `layouts/blog_posts.liquid`, you would configure it by providing a `title` of `Blog Posts`. Note: without this option configured, it is impossible to configure anything else for a given layout.
`description`	No	`string` A description of the layout that will appear within the Live Editor admin interface.
`unique`	No	`boolean` Set this to `true` to indicate that only 1 page on the entire site may be based on this layout. This value defaults to `false`.
`file_name`	No	`string` Name of `.liquid` file to reference in the `layouts` folder. This defaults to the value of `title`, lowercased and underscored, followed by `_layout.liquid` (e.g., a `title` of `Blog Post` yields a `file_name` of `blog_post_layout.liquid`). If you override this default value, the file name must have a `.liquid` extension.
`regions`	No	`array` List of regions found within this layout. See the table below containing configuration options for regions.

Here are the options for configuring regions within each layout:

Option	Required	Description
`title`	Yes	`string` Title of the region. This will appear to content authors within the admin interface.
`var_name`	No	`string` This will be used to reference this region within a `region` tag in the layout’s `.liquid` template. If not provided, this defaults to the value of `title`, all lowercase and underscored (for example, if the title is `Author Name`, the default value to use within the code would be `author_name`).
`description`	No	`string` Description of the region that will appear as a tooltip within the Live Editor admin interface.
`content_templates`	No	`array` List of content template `var_name`s that will be accepted into this region. This is useful to limit the type(s) of content that can be added to a region.
`max_num_content`	No	`number` Maximum number of content items that can be added to this region. Live Editor will disable the control for adding content to this region once the limit has been reached.

To show you a more full-fledged layouts.json, here is an expanded example that includes a 2nd layout called “Home Page” and more examples of configurations of the layouts and regions within:

layouts.json

        {
          "layouts": [
            {
              "title": "Site",
              "description": "Global layout for all pages in the site.",
              "regions": [
                {
                  "title": "Main"
                },
                {
                  "title": "Footer",
                  "content_templates": [
                    "text",
                    "google_map"
                  ]
                }
              ]
            },
            {
              "title": "Home Page",
              "unique": true,
              "file_name": "home",
              "regions": [
                {
                  "title": "Hero",
                  "var_name": "banner",
                  "content_templates": [
                    "text",
                    "image"
                  ]
                },
                {
                  "title": "Main"
                }
              ]
            }
          ]
        }

Marking up layout templates with Liquid

Now it’s time to code up the HTML, CSS, and JavaScript that will make up your website’s interface.

A typical layout will contain these elements:

Regions for content authors to add content into.
Global, local, and contextual navigation.
Metadata and asset includes in the document’s <head> section.

Let’s examine each of these tasks in detail.

Editable regions

Adding editable regions to a layout is simple enough using the region Liquid tag:

        <main>
          <article>
            {% region 'main' %}
          </article>
          <aside>
            {% region 'sidebar' %}
          </aside>
        </main>

The argument passed to the region tag corresponds to the var_name value configured in the layouts.json file. If a region with that title is absent from layouts.json, the configuration of the region is assumed to consist of all default settings.

Once one or more regions are defined in the layout, the Live Editor admin will allow content authors to add content to the them from the admin interfaces.

Navigation menus

Global and local navigation menus are often repeated across pages, so it usually makes sense to include them in one or more of your layouts.

See our guide about Navigation Menus for more information about working with navigation menus in your theme.

Metadata and including assets in the document’s `<head>`

Live Editor provides a series of objects and filters that enable you to build the metadata and include assets needed in your documents’ <head> section.

Rendering page metadata

Below are samples of objects available for outputting page metadata in the <head> section:

Example layout <head>

        <head>
          <-- Page title is typically best used in the document title -->
          <title>{{ page_title }}</title>
      
          <-- Meta description -->
          {% if page_description %}
            <meta name="description" content="{{ page_description }}">
          {% endif %}
      
          <-- Robot directives -->
          <meta name="robots" content="{{ page_robots }}">
      
          <-- Canonical URL -->
          <link rel="canonical" href="{{ canonical_url }}">
        </head>

Linking to static assets (CSS, JS, images, etc.)

To link your layouts to CSS files, you can reference the file by path from the root assets folder of your theme and chain the asset_url and stylesheet_tag filters:

Linking a style sheet located at assets/css/site.css

{{ 'css/site.css' | asset_url | stylesheet_tag }}

Similar to CSS, to include JavaScript files in your layouts, you can reference the file by path from the root assets folder and chain the asset_url and script_tag filters:

Including a JavaScript file located at assets/js/site.js

{{ 'js/site.js' | asset_url | script_tag }}

Other types of assets work similarly with the asset_url filter within the context of their respective HTML tags:

        <-- Favicon references an image at assets/images/icons/favicon.ico -->
        <link rel="shortcut icon" href="{{ 'images/icons/favicon.ico' | asset_url }}">
      
        <-- Apple Touch icons reference images in assets/images/icons -->
        <link rel="apple-touch-icon" href="{{ 'images/icons/apple-touch-iphone.png' | asset_url }}">
        <link rel="apple-touch-icon" sizes="72x72" href="{{ 'images/icons/apple-touch-ipad.png' | asset_url }}">
        <link rel="apple-touch-icon" sizes="114x114" href="{{ 'images/icons/apple-touch-iphone4.png' | asset_url }}">
        <link rel="apple-touch-icon" sizes="144x144" href="{{ 'images/icons/apple-touch-ipad-retina.png' | asset_url }}">

Adding more layouts to the theme

Using Live Editor CLI, you can run the liveeditor generate layout command to add a new layout to your theme:

liveeditor generate layout "Home Page"

This will add a new layout template file at layouts/home_page_layout.liquid and add an entry for it to layouts/layouts.json.

Configure and code it from there to your heart’s desire.

Design consideration: when to store content directly in the layout vs. as content in the CMS

Sometimes it can be a little unclear as to what content and assets you should be storing in your theme directly vs. having content authors add as a content item to each page.

A common question: Should the company’s address be hardcoded into the footer of the theme’s layout, or should content authors be able to edit it? This question can also apply to the website’s logo and other elements of the header and footer.

Consider the following when making the decision:

How often will the element need to be changed?

If the element is the same across the entire site and is likely only to be changed perhaps with a major change to the business or a new website design, then consider leaving it in the theme.

If the element will need to be changed often and you are short-staffed on people who know how to code Live Editor themes, then consider adding an editable region in its place for content authors to work with.

Would content authors be likely to mess up a major part of the design if the element were editable in the CMS?

Intrinsically, you probably already know the answer to this question. Some organizations consist of many web-savvy professionals, and others don’t. Live Editor layouts with editable regions are designed to protect the website’s integrity from those who aren’t quite as web-savvy.

Next steps

Learn how to configure and mark up navigation elements with our Navigation Menus guide.