Theme Structure
A theme controls the setup, features, and appearance of a merchant's online store. The theme code is organized with a standard directory structure specific to SHOPLINE themes, along with supporting assets like images, CSS, and JavaScript. To learn how themes fit into SHOPLINE and how to set up an environment for building and testing themes, refer to the SHOPLINE Theme Overview.
If you are creating a theme for the SHOPLINE Theme Store, you need to meet certain requirements, such as the customization options your theme offers, its design, and included features.
Content
Theme files can be grouped into the following categories:
- Markup and Features - These files handle the layout and functionality of the theme. They use Handlebars templates to create the HTML for the store's pages.
- Supporting Assets - These files include assets, scripts, or local files that are used by other theme files.
- Configuration Files - These files store configuration data in JSON, which merchants can customize using the Theme Editor.
Markup and Features
The following components determine the layout of each page:
| No. | Component | Description |
|---|---|---|
| 1 | Layout Files | The foundation of the theme. Use layout files to hold repeating theme elements like headers and footers. |
| 2 | Template Files | Templates that control the content displayed on a page. Each theme should include different types of templates for various content types, like the Homepage and Product Detail Page. |
| 3 | Template-rendered Sections | Reusable, customizable content modules. |
| 4 | Blocks within each section | Reusable, customizable content pieces that can be added, removed, and rearranged in sections. |
The content on pages in themes can be implemented in templates, sections, blocks, and snippets. The look and interactive features of themes can be achieved using Handlebars, CSS, and JavaScript. The features of a theme determine how customers interact with the online store's content. For example, your theme should allow customers to add products to the cart using a product type Handlebars form helper.
Supporting Assets
Supporting assets control the look and functionality of components or store reusable code.
For example, you need assets to style the theme. These assets help display the merchant's brand by defining the online store's look and feel through CSS and JavaScript applied to layout, template, and section files.
Store reusable Handlebars and HTML snippets in the snippets directory. Store the theme's CSS and JavaScript in the assets directory.
Additionally, you can translate your theme into different languages using localization files. Localization files contain translations for text strings used throughout the theme and are stored in the theme's locales directory.
Allowing for Customization of Theme Components
Merchants can customize their themes from the SHOPLINE backend using the SHOPLINE Theme Editor. Themes can offer various customization options, allowing merchants to create the customer experience they want:
- Make your theme templates modular by creating multiple sections and blocks. Refer to our Best Practices for Sections and Blocks to design sections and blocks effectively.
- Create settings that let merchants control the appearance or behavior of the theme. Merchants can set dynamic values for settings using dynamic sources.
Directory Structure and Component Types
Themes must use the following directory structure:
├── assets
├── config
├── layout
├── locales
├── sections
├── snippets
└── templates
└── customers
To upload a theme to SHOPLINE, the following files must be included:
layout/theme.htmlconfig/settings_data.jsonconfig/settings_schema.json
Assets
The assets directory contains all assets used in the theme, including images, CSS, and JavaScript files.
Use the assets_url helper to reference assets within the theme.
Config
The config directory contains the theme's configuration files. Configuration files define settings in the Theme Editor's settings area and store their values.
Theme settings are a good place to store general settings such as typography and color options. Access theme settings via the settings object.
Layout
The layout directory contains the theme's layout files, which display template files.
Layouts are HTML files used to define reusable layouts across multiple page types. For example, layouts are a good place to include any content you might want in the <head> element as well as headers and footers.
The theme.html file must be in this folder for the theme to be uploaded to SHOPLINE.
Locales
The locales directory contains the theme's locale files, which provide translated content. Locale files enable you to offer a translated experience in the Theme Editor, provide translations for the online store, and allow merchants to customize text within the online store.
Sections
The sections directory contains all the theme's section files.
Sections are HTML files that allow you to create reusable content modules that can be customized by merchants. They can also include blocks, which let merchants add, remove, and rearrange content within a section.
Snippets
The snippets directory contains smaller HTML files hosting reusable code snippets. You can reference these snippets throughout the theme using the Handlebars snippet helper.
Templates
The templates directory contains the theme's template files, which control the rendering of each type of page.
The templates/customers directory contains template files for customer-centric pages, such as login and account overview pages.
You can use templates to add functionality that makes sense for the page type. For example, you can add extra product recommendations to a product template or a comment form to a blog post template. You can also create multiple versions of the same template type to create custom templates for different uses.
Templates are not required. However, you need a matching template for any page type you want to render. For instance, to display a product detail page, you need at least one product type template.
