Theme Architecture

A theme controls the organization, features, and style of a Basker site. Theme code is organized with a standard directory structure of files specific to Basker themes, as well as supporting assets such as images, stylesheets, and scripts. To learn how themes fit into Basker, and learn how to set up an environment to build and test themes, refer to the Basker themes overview.

Content

Theme files fall into the following general categories:

• Markup and features: These files control the layout and functionality of a theme. They use Liquid to generate the HTML markup that makes up the pages of the merchant’s online store.
• Supporting assets: These files are assets, scripts, or locale files that are either called or consumed by other files in the theme.
• Config files: These files use JSON to store configuration data that can be customized via the studio using the theme editor.

Markup and features

The following components determine the organization of each page:

Number	Component	Description
1	Layout	Defines the overall structure of the page
2	Template	Specifies the content and arrangement of elements within the layout
3	Blocks	Reusable sections of content or functionality

Features can be introduced into themes in Liquid template files, components, blocks, and snippets. You can implement theme features using Liquid, CSS, and JavaScript. A theme’s features determine how end-users can interact with the site content.

Supporting assets

You can add supporting assets to your theme to control the presentation of components and features, or to store reusable pieces of code that can be used across components.

For example, you need to add assets to style the theme. These assets help to express the merchant’s brand by defining the online store’s aesthetic and how content sections are styled. The theme’s style is defined by the CSS and JavaScript that are applied to layout, template, and block files.

You can store the Liquid and HTML that you want to reuse across your theme in snippets. Store the theme’s CSS and JavaScript in the theme’s assets directory.

In addition, you can translate your theme into different languages using locale files. Locale files contain a set of translations for text strings used throughout the theme. Store locale files in the locales directory of the theme.

Allowing for customization of theme components

Admins can customize their theme from the Basker Studio by using the Basker theme editor. Themes can offer different customization options to enable admins to create their desired user experience:

You can create settings to allow admins to control the appearance or behavior of the theme in config/settings.json.

Directory structure and component types

Themes must use the following directory structure:

• Directoryassets/

  • …
• Directoryconfig/

  • …
• Directorylayouts/

  • …
• Directorylocales/

  • …
• Directorycomponents/

  • …
• Directorysnippets/

  • …
• Directorytemplates/

  • …

Subdirectories, other than the ones listed, aren’t supported.

assets

The assets directory contains all of the assets used in a theme, including image, CSS, and JavaScript files.

Use the asset_url Liquid URL filter to reference an asset within your theme.

config

The config directory contains the config files for a theme. Config files define settings in the Theme settings area of the theme editor, as well as store their values.

Theme settings are a good place to host general settings such as typography and color options. Theme settings can be accessed through the settings object.

Note

You can also create settings for sections and blocks. These settings are defined as part of the parent section or block object, and appear in the theme editor with the associated object.

layouts

The layouts directory contains the layout files for a theme, through which template files are rendered.

Layouts are Liquid files that enable you to include content that should be repeated on multiple page types in a single location. For example, layouts are a good place to include any content you might want in your <head> element.

A default.liquid file must exist in this folder for the theme to be uploaded to Basker.

locales

The locales directory contains the locale files for a theme, which are used to provide translated content. Locale files allow you to provide a translated experience in the theme editor, provide translations for the online store, and allow merchants to customize text in the online store.

blocks

The blocks directory contains a theme’s blocks. Blocks are Liquid files that allow you to create reusable modules of content that can be configured in the Basker Studio. Each file controls how they are configured using a JSON schema as well as rendered.

snippets

The snippets directory contains Liquid files that host smaller reusable snippets of code. You can reference these snippets throughout the theme with the Liquid render tag.

templates

The templates directory contains a theme’s template files, which control what’s rendered on each type of page.

You can use the template to add functionality that makes sense for the page type. For example, you can add additional event recommendations to a event template. You can also create multiple versions of the same template type to create custom templates for different use cases.

No templates are required. However, you need to have a matching template for any page type that you want to render. For example, to render a product page, you need at least one template of type product.