Templates & widgets

Overview

Components	Description
Widgets	UI elements in Shopify liquid syntax. The raw code files can be customized by using the Code Editor, giving full control for developer to implement their UIs.
Template	Group of widgets bundled together so that it can be easily installed to a Shopify theme. There are different built-in templates that match different Shopify themes such as Dawn, Broastcast, etc. So when users install TURBO, typically they select one of their existing themes and choose a template that matches the theme. Technically, a template ID is attached to the theme via app embed. So when the page load, the theme will fetch and render the correct template's widget base on its ID and location. You can inspect the request https://services.mybcapps.com/bc-sf-filter/... and look for the query params widgetId. Its value would be like {templateID}/themes/{type}/main__0__liquid. The raw widget code can be referenced in the Code Editor at /shopify-integration/code-editor/{templateID}, file src/themes/main.liquid respectively.
Settings	Style settings for widget appearance. These settings are coded in the widgets. By using Visual Editor, you can customize their value, and by using Code Editor, you can also control where and how they are applied
Customization files	CSS and JavaScript files for extending styles and functionalities

Template language: Shopify Liquid

TURBO widgets use Shopify liquid template language which is the backbone of every Shopify theme. So if you are experienced Shopify developer, you should be familiar with our widgets. If you don't, we recommend to take some time to learn its concepts first. Below's some good brief introduction, extracted from Shopify learning guide (PDF).

A .liquid file is a mix of standard HTML code and Liquid constructs. It’s an easy to read syntax, and is easy to distinguish from HTML when working with a template file. This is made even easier thanks to the use of two sets of delimiters: The double curly brace delimiters {{ }} denote output, and and the curly brace percentage delimiters {% %} denote logic.

Another way of thinking of delimiters is as "placeholders". A placeholder can be viewed as a piece of code that will ultimately be replaced by data when the compiled template is sent to the browser. This data is determined entirely by the theme designer as a result of the Liquid code in the template.

As such, Liquid templates, much like templates that intersplice PHP and HTML, serve as representations of what will be rendered.

Code Editor

Our code editor UI is similar to Shopify's theme editor. However, there are some differences:

Editor	Shopify Theme Editor	TURBO Code Editor
File structure	Files are group into element types: template, section, snippet, etc.	Files are grouped into functional UI blocks
Settings support	Allow to customize settings schema and data in JSON	Doesn't allow to change settings value. (Use Visual Editor instead)
CSS/JS support	Allow to fully customize theme CSS/JS that are located in assets/	Allow to customize CSS/JS via exposed customization files: customization.css and customization.js

Liquid widgets navigation

• All liquid widgets are located in the src/ folder. Widgets are organized into functional UI blocks such as filter-tree, search, cart, etc.
• By convention, main.liquid serves as the entry point file in each folder.
• To access and work with settings, use the {% settings %} tag as shown in this example:

<!-- TEMPLATE FILTER VERTICAL -->
<!-- Assign the 'filterLayout' setting value to a local variable -->
{% settings assign filterLayout = filterSettings.filterLayout %}

<!-- Now you can work with the local variable without using {% settings %} -->
{% if filterLayout == 'horizontal' %}
    {% assign filter_style = filter_style | append: 'boost-sd__filter-option--' | append: filterTreeHorizontalStyle | append: ' boost-sd__filter-option--' | append: filterLayout %}
{% endif %}

• You can include other files using the {% render '{relative path to file}' %} tag. When processing templates, the TURBO compiler will bundle all linked files together. Therefore, variables declared in a parent file are accessible in the imported files. For instance, using the example above, the conditional check {% if filterLayout == 'horizontal' %} can also be used in any imported file.

Template Compilation Process

This section explains how the TURBO engine compiles .liquid files so that they can be properly rendered in the storefront.

The compilation process is triggered by any of these events:

• When a user installs a TURBO template in a theme
• When a user upgrades to a new template version
• When a user saves settings in the Visual Editor
• When a user saves a .liquid file in the Code Editor

During compilation, the TURBO engine bundles and processes all raw .liquid files along with their template settings into functional widgets. This bundling process follows the hierarchy established by the {% render %} tags in your files, ensuring all dependencies are properly included.

The resulting compiled widgets are accessible in the browser console through the object window.boostWidgetIntegration.app.production.template.

The compilation process generates the following widgets:

// Filter tree and product listing
- filter tree and product listing.liquid
- placeholder - filter tree.liquid
- product item.liquid
- product list.liquid
- product price.liquid
- refine by.liquid


// Filter Options
- filter option box item.liquid
- filter option list item.liquid
- filter option multi level collection item.liquid
- filter option multi level tag item.liquid
- filter option rating item.liquid
- filter option swatch item.liquid

// Search Functionality
- search page.liquid
- search tab collections content.liquid
- search tab collections content pagination.liquid
- search tab pages content.liquid

// Quick view & add to cart
- cart.liquid
- most popular products.liquid
- quick view.liquid

// Recommendations
- recommendation.liquid
- recommendation dynamic bundle.liquid
- recommendation embedded bundle.liquid
- recommendation placeholder.liquid
- recommendation volume bundle block.liquid
- recommendation volume bundle popup.liquid
- recommendation volume bundle product.liquid

// Additional Features
- back in stock.liquid
- collection header.liquid
- pre order.liquid
- preorder placeholder.liquid

Template Settings

TURBO templates support a sophisticated configuration object that allows for granular customization of layouts and styles. To explore the complete settings data for your theme, you can access it through the browser console at window.boostWidgetIntegration.app.production.templateSettings.

While you can reference these settings programmatically, please note that modifications to these settings can only be made through the Visual Editor.

Customizing CSS

To customize the styles, edit the assets/customization.css file. This file allows you to apply custom styles to the user interface.

Customizing JavaScript

To customize JavaScript events, edit the assets/customization.js file. This file allows you to register custom functions for various events and extend or modify their behavior.

Reference to customize-javascript for more detail