All Tutorials

App sections

All Tutorials

App sections

App sections

App sections use the sections architecture to make it easier for merchants to add app content to their online store.

Sections are self-contained Liquid files made up of Liquid code and a schema. All the pages in a merchant's online store contain a combination of sections. The following diagram shows how an app section integrates with other sections to create to create a page on a store.

Section types and how they combine on a theme page

Add an app section

  1. From your Partner Dashboard, click Apps.
  2. Click the name of your app.
  3. Click Extensions.
  4. Click Online Store.
  5. Click Add section on the App sections card.
  6. Add a section title. Choose something that is distinct and recognizable because the title can't be changed after you save.
  7. Click Upload file, or drag a liquid file to add it to the app section.
  8. Click Save

Limitations

App sections have the following limitations:

Compatibility

App sections can only be used if a merchant has installed a sections-compatible theme. Within your app, check if Pages/{page-type}.liquid exists in order to see if sections have been enabled for a given page.

If a merchant's theme does not have sections enabled, use app snippets to add custom code to legacy theme templates.

Examples

The following app section example can be used right away. This example shows a configurable header and a list of reviews. To understand what can be included in a section schema, see the AppSectionSchema.

<h1>{{ section.settings.header }}</h1>
{%- assign count = section.settings.reviews_count | escape -%}
<ul>
{% for i in (1..count) %}
 <li>Review number {{ forloop.index }}</li>
{% endfor %}
</ul>

{% schema %}
 {
   "name": {
     "en": "Product review",
     "fr": "Revues de produits"
   },
   "supports": ["product"],
   "settings": [
     {
       "type": "text",
       "id": "header",
       "label": "Header",
       "default": "Product reviews"
     },
     {
       "type": "range",
       "id": "reviews_count",
       "label": "Reviews count",
       "default": 4,
       "min": 1,
       "max": 10,
       "step": 1
     }
   ]
 }
{% endschema %}

Building on the previous example, the following example shows how to use an App section to display a list of reviews that are saved as two product metafields (reviews-comment and reviews-rating) with a shared key:

<h1>{{ section.settings.header }}</h1>
{% assign count = section.settings.reviews_count | round %}
<ul>
{% for field in product.metafields.reviews-comment limit:count %}
    {% assign key = field | first %}
    <li>{{ product.metafields.reviews-rating[key] }}</li>
    <li>"{{ field | last }}"</li>
    </br>
{% endfor %}
</ul>

{% schema %}
 {
   "name": {
     "en": "Reviews",
     "fr": "Revues de produits"
   },
   "supports": ["product"],
   "settings": [
     {
       "type": "text",
       "id": "header",
       "label": "Header",
       "default": "Reviews"
     },
     {
       "type": "range",
       "id": "reviews_count",
       "label": "Reviews count",
       "default": 4,
       "min": 1,
       "max": 10,
       "step": 1
     }
   ]
 }
{% endschema %}

AppSectionSchema

You can add app section files in your Partner Dashboard. Merchants can then add the apps sections to their theme.

{
 "name": <String>,
 "tag": <String>,
 "class": <String>,
 "supports": [<LocationType>],
 "settings": [<SettingSchema>],
 "default": [<SectionDefaultData>],
 "blocks": [<BlockSchema>],
 "max_blocks": <Integer>,
 "locales": <LocalesSchema>
}

SettingSchema

{
  "type": <SettingType>,
  "id": <String>,
  "label": <String>,
  "placeholder": <String>,
  "default": <Value>
  "info": <String>
}

BlockSchema

{
  "id": <BlockId>,
  "type": <BlockType>,
  "settings": {
    <SettingId>: <SettingData>
  }
}

AppSectionSchema property definitions

AppSectionSchema property definitions
Property Required? Definition
name Yes The section name.
tag No Specifies the HTML tag of the section wrapper.
class No Specifies additional classes for the section wrapper in the schema.
supports No

The supported values are:

  • ["product", "collection"] - An array of page paths.
  • "all" - The section can be added to all page types.

If the field is not present, then it defaults to all.

settings No Configures the theme settings that merchants can access using the theme editor. See the Settings schema for a description of the attributes. For a list of supported setting types, see Input setting types. You can only define up 10 settings for each section in the schema.
default No Defines the default configuration of the section.
blocks No Defines blocks that contain settings and content that can be added, removed, and re-ordered by the merchant. You can only define up to 12 block for each section in the schema.
max_blocks No Sets the maximum number of blocks the merchant can add to the app section.
locales No Uses the global translations defined in the locales directory. The translate and localize filters work in sections the same way they do in other templates. Sections can also define their own translations in their schema.

Testing your app section

After you've configured your app section, you can use one of the following way to test your app: