Skip to main content

App blocks for themes

If your section is part of a Liquid templates, then you should support blocks of type @app. These blocks enable app developers to create blocks for merchants to add app content to their theme without having to directly edit theme code.

📘 Note

Blocks of type @app aren't supported in statically rendered sections.

To support app blocks, you need to do three things:

Support app blocks in the section​

To allow merchants to add app blocks to a section, you need to include a generic block of type @app in the section schema. For example:

"blocks": [
  {
    "type": "@app"
  }
]

🚧 Caution

Blocks of type @app don't accept the limit parameter. Including this will result in an error.

Render app blocks​

To render an app block, you need to check for the appropriate type, and use the following code:

{% render block %}

For example:

{% for block in section.blocks %}
  {% if block.type contains 'shoplazza://apps' %}
    {% render block %}
    ...
  {% endif %}
{% endfor %}

App block wrapper​

App blocks can be added to a page in two ways:

  • As a block within the confines of the section that's rendering the block
  • In a similar manner to sections, giving them the full width of the page to render content

As app blocks aren't sections themselves, Shoplazza wraps these full-width app blocks in a platform-generated section by default. However, you can override this default section by creating your own section called apps.liquid.

The apps.liquid section schema needs to include a block of type @app, as well as a preset. If either of these is missing, then an Apps not supported or Apps section is invalid error is returned in the theme editor and merchants aren't able to use the section.

🚧 Caution

The apps.liquid section schema can't contain the templates schema attribute. It's expected that this section is available on all templates.

For example:

{% for block in section.blocks %}
  {% render block %}
{% endfor %}

{% schema %}
{
  "name": "apps",
  "max_blocks": 16,
  "settings": [],
  "blocks": [
    {
      "type": "@app"
    }
  ],
  "presets": [
    {
      "name": "apps",
      "cname": {
        "en-US": "Apps",
        "zh-CN": "应用"
      },
      "category": {
        "en-US": "Apps",
        "zh-CN": "应用"
      },
      "display": true,
      "blocks": []
    }
  ]
}
{% endschema %}

To enable merchants to control how the app looks inside of an app section, you can add a setting that lets merchants add margins around the app blocks. This helps make the app section margins consistent with your theme's layout.

<div class="{% if section.settings.page_width %}page-container{% endif %}">
  {% for block in section.blocks %}
    {% render block %}
  {% endfor %}
</div>

{% schema %}
{
  "name": "apps",
  "max_blocks": 16,
  "settings": [
    {
      "type": "checkbox",
      "id": "page_width",
      "label": {
        "en-US": "Make section margins the same as theme",
        "zh-CN": "使分区页边距与模板相同"
      },
      "default": false
    }
  ],
  "blocks": [
    {
      "type": "@app"
    }
  ],
  "presets": [
    {
      "name": "apps",
      "cname": {
        "en-US": "Apps",
        "zh-CN": "应用"
      },
      "category": {
        "en-US": "Apps",
        "zh-CN": "应用"
      },
      "display": true,
      "blocks": []
    }
  ]
}
{% endschema %}

📘 Note

The apps.liquid section isn't a standard theme section. It can't be manually rendered, meaning you can't include it with {% section 'apps' %}, and it won't show up in the theme editor for merchants to add to pages.