Creating a Dynamic Section for a Shopify theme

Dynamic sections are a neat bit of functionality that you can leverage in a Shopify theme. You can place them statically in page templates that you create just as you would static ones. Dynamic sections, however, can be added to your store’s homepage when you customize it through the admin dashboard. When you add one of these sections to your homepage, not only can you configure it as you would a normal static one, you can also decide in which order it appears with respect to other dynamic ones.

The combination of allowing people to configure and arrange these types of sections on the homepage through the admin dashboard is quite powerful and helps reduce dev maintenance costs. There is a rather complete tutorial on them here though the code samples have a lot to them. In this tutorial, I am going to show how to create a bare bones one that can be used as a starting point for developing others.

Step 1 – Setup your dev environment

If you want to follow along with this tutorial. You should setup a Shopify development store. They are free and you can make as many as you like. You should also install Theme Kit. It is a great little command line tool that will let you download and upload your theme to your store. After you install Theme Kit, configure it to use your development store as its development environment. The github.io link I posted includes a very good step by step instructions on how to do that.

Once you have Theme Kit configured, download the starter theme that your development store comes with:

> theme download

You can use an existing theme that you are already working with too but in this post I am just going to keep things simple. If you do use an existing one, then just deploy it to your development store in order to overwrite the starter one.

Turn on watch mode. When Theme Kit is running in that mode, any changes that it sees will automatically get pushed to your store.

> theme watch

In a browser, you should have the Shopify admin dashboard open for your development store as part of the Theme Kit setup. If you already closed it, you should reopen it since you will use it to view the dynamic section you create.

Step 2 – Sanity check your theme

The template for your homepage is in templates/index.liquid. In order for your homepage to display dynamic sections, your template needs to contain this bit of code:

{{ content_for_index }}

Not every theme you are going to work with will have the above code in its index.liquid. This is especially true for themes that you inherit. You can put it anywhere in your template so you are in full control of where your dynamic sections are rendered.

Step 3 – Create a basic dynamic section

Create the following file sections/hello_dynamic_section.liquid:

<h1>Hello Dynamic Section</h1>

{% schema %}
{
    "name": "Hello Dynamic",
    "class": "hello-dynamic",
    "presets": [
        {
            "category": "Hello",
            "name": "Example"
        }
    ]
}
{% endschema %}

That is all you need to have for a very simple dynamic section. In the admin dashboard, select to customize your theme. The editor will show the sections that are being displayed on the page in the left panel; make sure you are viewing the homepage. If this is a brand new store, you might only see an Add section button. Click it and you will see the dynamic sections that are available in your theme. You will see the simple Hello Dynamic one you just created. Click the Add button next to Example in the Hello category and Hello Dynamic Section will be placed on your homepage.

A section in Shopify has two components: a template and a schema. The template is the layout for the section and the schema is the data that can be applied to it. In the above example, the template consists of an h1 tag. The schema contains the name of the section and the CSS class that is applied to the div tag that wraps it when it is added to the homepage. The presets array is what makes the section dynamic. In the example, there is a single object in this array that has a category and a name that are displayed when the section is added via the theme editor. It isn’t entirely useful yet but the next step is to extend this preset object to support configurations.

Step 4 – Enable customizations

So this is where some of the magic starts to happen. The first extension you are going to add are settings. Update hello_dynamic_section.liquid to look like the following:

<h1>{{ section.settings.heading }}</h1>

{% schema %}
{
    "name": "Hello Dynamic",
    "class": "hello-dynamic",
    "settings": [
        {
            "type": "text",
            "id": "heading",
            "label": "Section Heading"
        }
    ],
    "presets": [
        {
            "category": "Hello",
            "name": "Example",
            "settings": {
                "heading": "hello heading"
            }
        }
    ]
}
{% endschema %}

The schema has been extended to have a settings array with a single member object. It has an id set to heading. The member of the presets array has also been extended to have a settings object with the property heading. It value hello heading is essentially its default value.

Refresh the browser that you are using to view the theme editor to see the updates that have been made to your dynamic section. When you now add it to your store’s homepage, you will have an option to set a field called Section Heading. You can add this section multiple times and give each one a different heading value.

Step 5 – Customizable blocks

The settings array allows you to have configurable properties in your section. It is pretty common to need a repeatable block in a section. Fortunately that is supported by Shopify with this other piece of magic. Update hello_dynamic_section.liquid to look like the following:

<h1>{{ section.settings.heading }}</h1>

{% for block in section.blocks %}
    <h2>{{ block.settings.subheading }}</h2>
{% endfor %}

{% schema %}
{
    "name": "Hello Dynamic",
    "class": "hello-dynamic",
    "settings": [
        {
            "type": "text",
            "id": "heading",
            "label": "Section Heading"
        }
    ],
    "blocks": [
        {
            "type": "subheadings",
            "name": "Subheadings",
            "settings": [
                {
                    "id": "subheading",
                    "type": "text",
                    "label": "Subheading"
                }
            ]
        }
    ],
    "presets": [
        {
            "category": "Hello",
            "name": "Example",
            "settings": {
                "heading": "hello heading"
            },
            "blocks": [
                {
                    "type": "subheadings",
                    "settings": {
                        "subheading": "hello subheading"
                    }
                }
            ]
        }
    ]
}
{% endschema %}

Refresh your browser again. Now when you add the dynamic section to the homepage, you should see in addition to the Section Heading field a Subheading one that you can add repeatedly. Each one will cause an h2 tag to be added.

The schema has been extended with a blocks array which has also been added to the presets object. A block object contains settings that behave just like the one previously defined in the schema. It allows you to specify different fields that can be set in the theme editor. I have added a for loop to the template that iterates over these blocks displaying all configured subheadings.

Closing thoughts

The key to creating themes with low maintenance costs is to enable as much customization through the admin dashboard as possible. It enables anyone to make UX updates to the store, not just people that know how to work with templates. That is why I really like Shopify’s dynamic sections so much; it lets anyone add a section to the homepage.