layout

The layout directory contains the theme's layout files, which define the basic framework of pages and enable consistent management of page structures and styles.

Layout files must include the following placeholders:

header: the header section
content: the page content
footer: the footer section

These placeholders are used to inject global scripts, such as JavaScript and CSS files, and render page contents.

Additionally, you can add custom HTML, CSS, or JavaScript in the layout files to apply the same changes across multiple pages.

Directory structure

The default layout file structure of the Bottle theme is as follows:

layout
├── gift_card.html   # Layout file for the gift card page
├── password.html    # Layout file for the password page
├── proofing.html    # Layout file for the store closing page 
└── theme.html       # Default layout page (automatically applied to all pages for which layout files are not specified)

You can also create custom layout files. The following shows an example:

layout
├── gift_card.html   		
├── password.html    		
├── proofing.html    		
├── theme.html       		
└── custom_layout.html	# Custom layout file

Layout file specification

File structure

The layout file must include the header, layout, and footer placeholders. You need to reference these placeholders through the content tag. You can also include custom code in the file to achieve a synchronized application across multiple page templates.

The following shows a basic layout file example:

<!DOCTYPE html>
<html>
<head>
  {{#content "header" /}}  <!-- The header placeholder -->
</head>
<body>
  {{#content "layout" /}}  <!-- The content placeholder -->
  
  {{#content "footer" /}}  <!-- The footer placeholder -->
  
  <!-- The custom script example -->
  <script>
    console.log('This is a custom script');
  </script>
</body>
</html>

Required placeholders

The following table explains the required placeholders in the layout file.

Placeholder	Injected content types	Typical use cases
header	+ Common scripts + Styles + App resources	+ Theme event SDK + Custom code app
layout	+ Page body HTML	+ Page details + Cart page template
footer	+ Common scripts + Styles + App resources	+ Event tracking + Performance monitoring scripts

Layout application

JSON template

In a JSON template, use the layout field to specify the layout file you want to use for the page.

The following example shows the use of the password.html layout file for the store's password protection page:

// In templates/password.json, specify the layout field.
{
  "layout": "password",  //Specify layout/password.html
  "sections": {
    "main-password": {
      "type": "password"
    }
  },
  "order": ["main-password"]
}

HTML template

In an HTML template, use the layout tag to specify the layout file you want to use for the page.

The following example shows the use of the proofing.html layout file for the store closing page:

<!-- In templates/proofing.html, specify the layout field. --> 
{{#layout "proofing" /}}  <!-- Explicitly refer to layout/proofing.html --> 
<div class="page-width stage__proofing">
  <div>
    <img width="240" height="160" src="{{`images/image-store-close.png` | asset_url()}}" alt="close the store" />
    ...
  </div>
</div>

Caution: When you do not specify a specific layout file for a page template, layout/theme.html is automatically used as the default.

Best practices

Enhance the default layout

Set responsive viewport <meta> tags in the default layout file theme.html, as shown in the following example:

<!DOCTYPE html>
<html>
<head>
  <!-- Customize the meta tag --> 
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  {{#content "header" /}}
</head>
<body>
  {{#content "layout" /}}
  
  {{#content "footer" /}}
</body>
</html>

Design for scalability

Leverage CSS class names to differentiate layout types, thereby optimizing global style management. The following shows an example:

<!DOCTYPE html>
<html>
<head>
  {{#content "header" /}}
</head>
<body class="layout-{{ layout.name }}">	<!-- Customized class -->
  {{#content "layout" /}}
  
  {{#content "footer" /}}
</body>
</html>