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:

• Add support for app blocks to the section
• Render the block content

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.