Theme Directory

Themes determine the look and feel of a website. Lightning themes are made up of a mix of .twig and .json files in a specific directory structure. Theme files should be written without knowledge of specific site data (like which items are in the catalog) so that a theme can be applied to any site.

Directory Structure

theme
├── assets
│   ├── css
│   ├── fonts
│   ├── images
│   └── js
├── components
│   └── sections
├── config
├── editor
│   └── manifest.html.twig
├── layouts
│   └── theme.html.twig
├── partials
└── templates
    └── pages
        └── default.html.twig

Assets Directory

Static files that you want to reference in your templates should be stored in the assets directory. You are free to make any subdirectories you want under assets and add, replace, or modify CSS files and other assets as needed.

Components Directory

Components are templates that use schemas to define the parameters they expect to use in their markup.

At the moment, there is one type of schema supporting component:

• Sections

Config Directory

The config directory contains json files. The properties defined in these files can be used within templates. You are free to give your config files any names you want.

config/colors.json
{
  "heading": "red"
}

templates/page/default.html.twig
<h1 style="color: {{ config.colors.heading }}">Heading</h1>

localize function

This has the same behaviour as the localize filter with a slightly different syntax when used within your config files.

theme/translations/en.json

{
    "hello": "Hello",
    "helloMultiple": "Hello {{0}} and {{1}}",
    "helloMultipleNamed": "Hello {{name1}} and {{name2}}",
    "nested": {
        "hi": "Hi"
    }
}

theme/config/settings.json

{
    "hello": "localize:hello",
    "helloMultiple": "localize(['Tim', 'Brady']):helloMultiple",
    "helloMultipleNamed": "localize({name1: 'Tim', name2: 'Brady'}):helloMultipleNamed",
    "nested": "localize:nested.hi",
    "allTranslations": "localize:"
}

If you wish to include all translations, use localize: by itself. This can be especially helpful if you want to use translations heavily in JS (e.g. binding translations strings to the front-end via JS).

theme/templates/collection.html.twig

{{ config.settings.hello }}
{{ config.settings.helloMultiple }}
{{ config.settings.helloMultipleNamed }}
{{ config.settings.nested }}

Escaping functions

If you don’t want the functionality to be triggered for the function above and just want the raw string, simply prefix the function with \ (e.g. "\localize:hello").

Editor Directory

The editor directory contains the manifest.html.twig file where you can define the default_template property. This property specifies the default theme template to be used when creating new custom code pages via the UI.

Example

Define the default_template in your manifest file (/theme/editor/manifest.html.twig), for example:

{
    "default_template": "theme/templates/store/shop"
}

Creating Custom Code Pages

When you create a new custom code page via the UI, the default_template defined in the manifest file will be used if a specific template is not assigned. If the manifest file is invalid or if the default_template is not found, it will regress to use the templates/page/default.html.twig as the default template to create the page (if available).

Layouts Directory

Layouts are .twig templates to be extended by page templates. They allow you to include content that would be repeated on multiple pages.

Layouts should define twig blocks for areas that page templates should extend or override.

theme.html.twig is a theme’s default layout. If a page does not specify a layout it will use this layout.

Partials Directory

Partials are twig files that can be included in page templates or other partials. Their purpose is for code reuse and organization. Partials have access to the same parameter context as their parent template.

partials/example.html.twig

Example

templates/page/default.html.twig

<div>
	{{ include('partials/example') }}
</div>

Output

<div>
 	Example
</div>

Templates Directory

Templates determine what is rendered on a page. Currently, only page templates are supported. For more information, see Page Templates.