Getting Started

To create a new theme, you'll need to understand the basic file structure and create files accordingly.

Before we start, please ensure you have the following prerequisites:

A Shoplazza store: You can't work on a theme without a store.
A text editor: You can use any text editor or IDE of your choice, but VS Code is highly recommended for Shoplazza theme development due to its robust features and plugins, to develop locally, you will be using Shoplazza Theme Kit https://www.shoplazza.dev/docs/theme-kit. Or you can use the online build in Shoplazza theme editor.
Basic knowledge of HTML, CSS, JavaScript, and Liquid: Shoplazza themes are built with these technologies.

Step 1: Setup New Theme

To create a new theme, first, navigate to the "Online Store" -> "Themes" section on your Shoplazza admin panel. Click on the "Upload theme" button and upload a .zip file of your theme. If you're starting from scratch, you can download and modify an existing theme.

Step 2: Understand the File Structure

Once your theme is uploaded, it's essential to understand the file structure. Here's the basic directory structure of a Shoplazza theme:

my-new-theme/  
├── assets/  
    ├── style.css  
    ├── style.scss  
├── config/  
│   └── settings_data.json  
├── layout/  
│   └── theme.liquid  
├── locales/  
│   └── en.default.json  
├── sections/  
├── snippets/  
└── templates/  
    ├── 404.liquid  
    ├── article.liquid  
    ├── blog.liquid  
    ├── cart.liquid  
    ├── collection.liquid  
    ├── index.liquid  
    ├── list-collections.liquid  
    ├── page.liquid  
    ├── password.liquid  
    └── product.liquid

assets/: This directory contains all the theme's assets, like images, stylesheets, and JavaScript files.
config/: This directory contains the theme's settings files.
layout/: This directory contains the theme layout files. theme.liquid is the main file used for the layout.
locales/: This directory contains the theme's locale files, which are used for text content on your store.
sections/: This directory contains the theme's sections. Sections are reusable modules of content that can be customized and re-ordered by users.
snippets/: This directory contains the theme's snippets, small bits of reusable code.
templates/: This directory contains all other types of content, like product pages, blog posts, etc.

Step 3: Start Building Your Theme

Once you have the basic structure set up, you can start building your theme. Each of the directories serves a different purpose, and you should structure your files accordingly.

In the layout/ directory, you should have a theme.liquid file which defines the layout of your theme. This file contains the major HTML elements of your site like the <head>, <header>, <footer>, etc., and it wraps around the content of your pages.
In the templates/ directory, you create different Liquid templates for different types of pages like product pages, collection pages, article pages, etc.
In the sections/ directory, you create different sections that can be added to your pages through the Shoplazza admin. These are reusable modules of content.
In the snippets/ directory, you create small pieces of reusable code. These are typically used across multiple templates or sections.
In the assets/ directory, you store all your static files like images, stylesheets (CSS or SCSS), and JavaScript files.
In the config/ directory, you can set different configurable options that can be changed through the Shoplazza admin without editing the code.

Step 4: Preview Your Theme

After you have made changes to your theme, you can preview your theme in your Shoplazza store. Go to "Online Store" -> "Themes", click on the "Actions" button next to your theme, and then click on "Preview". This will open a new tab in your browser where you can preview your theme.

That's it! You've created a file structure for a Shoplazza theme and started building your theme. Remember, developing a Shoplazza theme requires a good understanding of HTML, CSS, JavaScript, and Liquid, so make sure to familiarize yourself with these technologies.

Theme Config

The settings_data.json file is an important part of any Shoplazza theme. It's located in the config/ directory and is used to store data from the theme settings that you can adjust from the theme editor in the admin interface.

This file is automatically generated and updated by the system when you change theme settings via the theme editor. The data in this file is represented in JSON format.

Here's a simple example of what the settings_data.json file might look like:

{  
  "current": "default",  
  "presets": {  
    "default": {  
      "section": {  
        "setting_name": "setting_value"  
      }  
    }  
  }  
}

The current key is used to specify the current preset that is being used. In this case, it's "default".

The presets key contains one or more named presets. Each preset is a collection of settings for the theme. The "default" preset is required and is used when you first install a theme. You can add additional presets as needed.

Each preset contains one or more sections, and each section can contain one or more settings. The settings are the actual theme settings that you can adjust via the theme editor. The setting values are usually simple types like strings or numbers, but can also be more complex types like arrays or objects, depending on the setting.

Here's a more complex example with multiple settings:

{  
  "current": "default",  
  "presets": {  
    "default": {  
      "colors": {  
        "body_text": "#333333",  
        "background": "#ffffff"  
      },  
      "typography": {  
        "base_font": "Helvetica, sans-serif",  
        "heading_font": "Georgia, serif"  
      },  
      "layout": {  
        "content_width": "1200px",  
        "sidebar_enabled": true  
      }  
    }  
  }  
}

In this example, the "default" preset has three sections: "colors", "typography", and "layout". Each section has multiple settings. For example, the "colors" section has settings for "body_text" and "background".

Note: Editing this file directly is not recommended as it's automatically managed by the system. You should use the theme editor in the admin interface to adjust theme settings.
For more information, you can refer our offical documentation https://www.shoplazza.dev/docs/overview-11

How to Use These Configs

In Liquid, the settings from the settings_data.json file can be accessed using the settings object. This allows you to use the settings data in your theme files.

Here's a basic example. Suppose you have the following data in your settings_data.json file:

{  
  "current": "default",  
  "presets": {  
    "default": {  
      "colors": {  
        "body_text": "#333333",  
        "background": "#ffffff"  
      }  
    }  
  }  
}

You can access the body text color in your Liquid files like so:

<p style="color: {{ settings.colors.body_text }}">This is some text.</p>

This will render the paragraph text in the color specified in the settings_data.json file.

Similarly, you can access the background color like this:

<body style="background-color: {{ settings.colors.background }}">
  <!-- Page content goes here -->
</body>

This will set the background color of the page to the color specified in the settings_data.json file.

You can use these settings in any Liquid tag, output, or filter. They're especially useful in conjunction with the style attribute in HTML tags, allowing you to customize the appearance of your theme based on the settings.

Remember that these settings can be changed from the theme editor in the admin interface, allowing you to adjust the appearance of your theme without editing the code.

Also, note that if a setting is not set, trying to access it in a Liquid file will result in null. You should check if a setting is set before trying to use it, like so:

{% if settings.colors.body_text %}
  <p style="color: {{ settings.colors.body_text }}">This is some text.</p>
{% endif %}

This will only render the paragraph if the body text color setting is set.
Notice that we also support different types of configs, please refer to https://www.shoplazza.dev/docs/overview-11 for more information.

Theme Layout

The theme.liquid file is the main layout file in Shoplazza themes. It contains the basic HTML structure of your site, including elements like the <head>, <header>, <footer>, and <body>, and it wraps around the content of your pages.
Here is a simple example of a theme.liquid file:

<!DOCTYPE html>

<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ shop.name }} - {{ page.title }}</title>

  {{ 'style.css' | asset_url | stylesheet_tag }}  
  {{ content_for_header }}

</head>
<body>
  <header>
    <h1>{{ shop.name }}</h1>
    <nav>
      <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/collections">Collections</a></li>
        <li><a href="/blog">Blog</a></li>
      </ul>
    </nav>
  </header>

  <main role="main">
    {{ content_for_layout }}
  </main>

  <footer>
    <p>&copy; {{ 'now' | date: "%Y" }} {{ shop.name }}</p>
  </footer>

  {{ 'script.js' | asset_url | script_tag }}  
  {{ content_for_js }}

</body>
</html>

In this example:

{{ shop.name }} and {{ page.title }} are Liquid variables. They dynamically pull in the name of your store and the title of the current page, respectively.
{{ 'style.css' | asset_url | stylesheet_tag }} and {{ 'script.js' | asset_url | script_tag }} are using Liquid filters to include a CSS file and a JavaScript file from your assets directory, respectively.
{{ content_for_layout }} is a special Liquid variable. It's where the content of your different templates (like product.liquid, collection.liquid, etc.) will be injected.
content_for_header: Injects code needed for Shoplazza features to work correctly. This can include things like the
Shoplazza analytics script, the customer login link, etc. This should be placed within the tag.
content_for_js: This is used to add specific JavaScript to the page dynamically. This variable should be placed right before the closing </body> tag.
The <header>, <main>, and <footer> elements contain the HTML for your site's header, main content area, and footer, respectively.
This is just a very basic example. Depending on your theme's design, your theme.liquid file can get much more complex, with more Liquid variables, filters, tags, and HTML.

More information can be found https://www.shoplazza.dev/docs/overview-9

Theme Locale

Here's how you can use locales in your theme:

Define Translations in JSON Files: You should define your translations in JSON files in the locales/ directory. The key structure should reflect your theme structure.

Here's an example:

{  
  "products": {  
    "product": {  
      "sold_out": "Sold out",  
      "save": "Save {{amount}}{{amount_symbol}}"  
    }  
  }  
}

Reference Translations in Your Theme: To reference these translations in your theme, you can use translation keys and the Liquid translation filter (t filter). You prepend the translation key with i18n.. For example:

<p>{{ 'i18n.products.product.sold_out' | t }}</p>

This would output "Sold out" in English, or the equivalent in the active language.

Interpolation: You can include variables in your translation strings, which can be dynamically populated when the string is referenced in Liquid. This is useful for including dynamic content in your translations.

Here's an example of how you can interpolate a translation:

<p>{{ 'i18n.products.product.save' | t: amount: 18.88, amount_symbol: '$' }}</p>

This would output "Save 18.88$", or the equivalent in the active language.

To switch between languages, you'll need to configure your store to support multiple languages and let your customers select their preferred language. The selected language will determine which locale file is used.
For more information, please refer to https://www.shoplazza.dev/docs/overview-6
Theme Section
In Shoplazza, a section is a reusable module of Liquid code that includes a specific piece of your online store's content. Sections can be static, like a header or footer, or dynamic, like a customizable product selector.

Sections are stored in the sections/ directory of your theme. Each section is stored in its own .liquid file.

Here's a basic example of how to write a Shoplazza section:

{% stylesheet %}  
h1 {  
  color: blue;  
}  
{% endstylesheet %}

{% javascript %}  
console.log('This is a custom section.');  
{% endjavascript %}

<h1>{{ section.settings.title }}</h1>
<p>{{ section.settings.content }}</p>
{% schema %}
{
  "name": "My custom section",
  "settings": [
    {
      "id": "title",
      "type": "text",
      "label": "Title",
      "default": "Default title"
    },
    {
      "id": "content",
      "type": "textarea",
      "label": "Content",
      "default": "Default content"
    }
  ]
}
{% endschema %}

In this example:

The {% schema %} and {% endschema %} tags define the section's schema. The schema includes the section's name and settings. Each setting has an id, a type, a label, and a default value. The id is used to reference the setting in the section's code. There are more input types you can find in the https://www.shoplazza.dev/docs/theme-settings-input-settings other than text and text areas being used in the exmaple
The {% stylesheet %} and {% endstylesheet %} tags define the section's CSS. This CSS will be included in the theme's main stylesheet when the section is included in a template.
The {% javascript %} and {% endjavascript %} tags define the section's JavaScript. This JavaScript will be included in the theme's main JavaScript file when the section is included in a template.
The {{ section.settings.title }} and {{ section.settings.content }} are Liquid variables. They dynamically pull in the values of the title and content settings.

This is just a basic example. Depending on your theme's design, your sections can get much more complex, with more settings, Liquid logic, HTML, CSS, and JavaScript.

You can include a section in a template using the {% section %} tag. For example, if your section's file is named my-custom-section.liquid, you could include it in a template like this:

{% section 'my-custom-section' %}

This would render the section in the template, and the section's settings would be configurable in the theme editor. Also, you can refer to How to Write a Section in Shoplazza Theme to see how to break down a existing first party section in shoplazza theme.

Theme Snippet

A snippet in Shoplazza is a chunk of reusable code that can be referenced in other Liquid templates. This is useful for keeping your code organized and DRY (Don't Repeat Yourself). Snippets are stored in the snippets/ directory of your theme.

Here's a basic example of how to create a snippet:

Create a Snippet File: You would create a new .liquid file in the snippets/ directory. For example, you might create a file named my-custom-snippet.liquid.
Write Your Snippet Code: You would then write your snippet code in this file. For example:

<p>This is a custom snippet.</p>

Include the Snippet in a Template: You can include the snippet in any of your Liquid templates using the include tag. For example:

{% include 'my-custom-snippet' %}

This would output "This is a custom snippet." wherever the include tag is used.

You can also pass parameters to your snippets. Parameters are variables that you define when you include the snippet, and they can be used within the snippet.

Here's an example of how to pass parameters to a snippet:

Create a Snippet File: You would create a new .liquid file in the snippets/ directory. For example, you might create a file named product-card.liquid.
Write Your Snippet Code: You would then write your snippet code in this file. For example:

<div class="product-card">
  <h2>{{ product.title }}</h2>
  <p>{{ product.description }}</p>
</div>

Include the Snippet in a Template with Parameters: You can include the snippet in any of your Liquid templates using the include tag and pass parameters to it. For example:

{% include 'product-card', product: featured_product %}

In this example, featured_product is a variable that's defined elsewhere in your template. This variable is passed to the product-card snippet as the product parameter.

Within the product-card snippet, you can use product to access the featured_product object. So {{ product.title }} would output the title of the featured_product, and {{ product.description }} would output the description of the featured_product.

This is a basic example. Depending on your theme's design, your snippets can get much more complex, with more parameters, Liquid logic, HTML, CSS, and JavaScript.

Hands on Examples & Liquid Objects

Liquid Objects

Liquid is a template language used in Shoplazza themes. It's used to load dynamic content on your storefront.

In Liquid, an object is a type of variable that represents something complex like a product, a collection, a cart, or the current page.

Objects have attributes which you can output or use in logic statements. For example, a product object has attributes like title, description, price, images, etc.

You reference an object and its attributes in your templates using dot notation. For example, if you have a product object named product, you can output the product's title like this: {{ product.title }}.

Here are some of the most common Liquid objects used in Shoplazza themes:

product: Represents a product. Has attributes like title, description, price, images, variants, etc.
collection: Represents a collection. Has attributes like title, description, products, etc.
cart: Represents the current user's shopping cart. Has attributes like items, total_price, etc.
customer: Represents the current user (if they're logged in). Has attributes like name, email, orders, etc.
page: Represents the current page. Has attributes like title, content, url, etc.
shop: Represents your Shoplazza store. Has attributes like name, description, url, products, collections, etc.

For more information, please refer to https://www.shoplazza.dev/docs/liquid-objects

These are just a few examples. There are many other Liquid objects, and each object has many attributes. You can find a full reference in the Shoplazza Liquid documentation. The following are the examples for how to use them.

How to Create a Navbar

Creating a header with dynamic menu links involves creating and using a snippet that reads from the store's linklist configuration.

First, create a file named header.liquid in the sections/ directory of your theme. This file will represent the header section of your theme. The code might look something like this:

<header class="site-header">
  <h1 class="site-title">{{ shop.name }}</h1>

  <nav class="main-navigation">
    {% include 'navigation', links: linklists.main-menu.links %}
  </nav>
</header>

In this example, we're including a snippet named navigation and passing the links from the main-menu linklist to it.

Next, create a file named navigation.liquid in the snippets/ directory of your theme. This file will contain the code for the navigation menu. The code might look something like this:

<ul class="menu">
  {% for link in links %}
    <li class="menu-item">
      <a href="{{ link.url }}">{{ link.title }}</a>
      {% if link.links %}
        <ul class="submenu">
          {% for sublink in link.links %}
            <li class="submenu-item">
              <a href="{{ sublink.url }}">{{ sublink.title }}</a>
            </li>
          {% endfor %}
        </ul>
      {% endif %}
    </li>
  {% endfor %}
</ul>

In this snippet, we're looping through each link in the linklist passed to the snippet. For each link, we create a list item and a link to the link's URL. If the link has its own links (indicating that it's a parent link with child links), we create a submenu and loop through the child links.

Finally, make sure to include the header section in your theme.liquid layout file:

<!DOCTYPE html>

<html lang="en">
<head>
  <!-- head content here -->
</head>
<body>
  {% section 'header' %}

  <!-- other content here -->

</body>
</html>

In the theme editor, you should be able to assign linklists to the main-menu linklist, and the navigation menu in your header should automatically update to reflect the links in the linklist.

Please note that this is a basic example, and you may need to adjust the code to match your theme's styles and structure.

How to Create Product Details Section

Creating a product detail section involves creating a section that can read and display information from a product object.

First, create a file named product-template.liquid in the sections/ directory of your theme. This file will represent the product detail section of your theme. The code might look something like this:

{% schema %}  
{  
  "name": "Product template",  
  "settings": [  
    {  
      "type": "checkbox",  
      "id": "show_vendor",  
      "label": "Show vendor",  
      "default": true  
    }  
  ]  
}  
{% endschema %}

{% if product %}

  <h1>{{ product.title }}</h1>
  <p>{{ product.description }}</p>
  {% if section.settings.show_vendor %}
    <p>{{ product.vendor }}</p>
  {% endif %}
  <img src="{{ product.featured_image | img_url: '480x480' }}" alt="{{ product.featured_image.alt | escape }}">
  <p>{{ product.price | money }}</p>
{% else %}
  <p>This product does not exist.</p>
{% endif %}

In this example, the section has a setting show_vendor, which can be toggled on or off in the theme editor. If it's on, the product's vendor is displayed. The section displays the product's title, description, vendor (if show_vendor is on), featured image, and price.

To display this section on a product detail page, you would use the product-template section in the product detail template. You would create a file named product.liquid in the templates/ directory of your theme, and the code might look something like this:

{% section 'product-template' %}

This will output the product detail section on the product detail page. The product object in the product-template section will automatically be the current product.

Again, this is a basic example. Depending on your theme's design, your product detail section can get much more complex, with more settings, Liquid logic, HTML, CSS, and JavaScript.

Shoplazza Theme Development Starter Guide