Framework​

Theme app extensions consist of App Blocks, App Embed Blocks, Assets, and Snippets.

File Structure​

When you create a theme app extension, SHOPLINE adds the following theme-app-extension directory and subdirectories to your app:

├── theme-app-extension
  ├── assets
  │   ├── app-block.css
  │   ├── app-block.js
  │   ├── app-embed-block.css
  │   ├── app-embed-block.js
  │   ├── logo.png
  │   └── sheep.jpg
  ├── blocks
  │   ├── app-block.html
  │   └── app-embed-block.html
  ├── locales
  │   ├── en.schema.json
  │   ├── zh-hans-cn.schema.json
  │   └── zh-hant-tw.schema.json
  ├── snippets
  │   └── logo-icon.html
  ├── .gitignore
  ├── .shopline-cli.yml

App Blocks​

Apps use App Blocks to inject content into the theme, enhancing its functionality. Merchants can add App Blocks to sections of the theme or as section-level components in page areas. Create App Blocks by targeting a section. By default, themes do not include App Blocks after installing an app. Merchants need to add App Blocks to the theme through the theme editor. Use App Blocks for apps that:

• Add product reviews or ratings to product details
• Cover the entire page width

Example​

This example creates a span element with a style attribute. The style value (color: {{ block.settings.textColor }}) looks for the textColor key in the settings of the schema, with a default value of #000000. This renders the text "App Block in SHOPLINE!" in black.

<span style="color: {{ block.settings.textColor }}">
App Block in SHOPLINE!
</span>
<img src="{{ asset_url 'logo.png' }}" />
{{ snippet 'app_snippet' }}
{{#schema}}
  {
    "name": "App Block",
    "target": "section",
    "stylesheet": ["app.css"],
    "javascript": ["app.js"],
    "settings": [
        {
          "label": "Color",
          "id": "textColor",
          "type": "color",
          "default": "#000000"
        }
    ]
  }
{{/schema}}

Example of App Block in Theme​

Here is an example of an App Block added to a section:

Here is an example of an independently added App Block:

Benefits of App Blocks​

App Blocks are flexible. Merchants can use the theme editor to add, remove, and reorder App Blocks at the section level, making customization easy.

App Embed Blocks​

Apps use App Embed Blocks to add non-UI elements and floating elements to the theme. SHOPLINE injects App Embed Blocks before the closing </head> and </body> tags in HTML. Set the target attribute in the schema to head or body to determine where the App Embed Block is rendered.

By default, App Embed Blocks are not automatically enabled after installation. Merchants need to activate them in the theme editor under Theme Settings > App Embeds.

Use App Embed Blocks for apps that:

• Provide floating elements like customer service widgets or announcement bars
• Add SEO meta tags, analytics, or custom forms

Example​

This example shows an App Embed Block inserted at the bottom of the body, rendering a floating comment button.

<div style="position: fixed; bottom: 0; right: 0">
  <img src="{{ asset_url 'comment.jpg' }}" />
</div>
{{#schema}}
  {
    "name": "App Embed Block",
    "target": "body",
    "settings": []
  }
{{/schema}}

Example of App Embed Block in Theme​

Benefits of App Embed Blocks​

All SHOPLINE online store themes support App Embed Blocks. After installation, merchants can configure App Embed Block settings in the theme editor for a more personalized experience.

Conditional App Blocks​

You can control the visibility of App Blocks or App Embed Blocks based on custom conditions. For example, you might want to limit content visibility based on location.

Include conditions in the schema under the available_if attribute, with the state stored in app metafields.

For example, if you have an app metafield with the namespace conditional and key block1, use the following schema:

{{#schema}}
{
   "name": "Conditional App Block Example",
   "target": "section",
   "stylesheet": ["app.css"],
   "javascript": ["app.js"],
   "available_if": "{{ apps.metafields.conditional.block1.value }}"
 }
{{/schema}}

Schema​

The schema for App Blocks and App Embed Blocks is similar to the theme section schema. It supports the following properties, some of which are unique to App Blocks and App Embed Blocks:

Locales Configuration​

{{#schema}}
{
  "locales": {
    "en": {
      "title": "Title"
    },
    "ja": {
      "title": "タイトル"
    },
    "de": {
      "title": "Titel"
    }
  }
}
{{/schema}}

Options Schema​

{{#schema}}
{
   "name": "App block",
   "target": "section",
   "stylesheet": ["app.css"],
   "javascript": ["app.js"],
   "settings": [
      {
        "label": "Select",
        "id": "select",
        "type": "select",
      	"options": "{{ apps.metafields.select.options.value }}"
      }
   ]
 }
{{/schema}}

Simplifying Installation with Deep Links​

After installation, your app can prompt merchants through deep links. When clicked, deep links activate the App Embed Block/App Block in the theme editor, allowing merchants to preview and adjust before saving and publishing. This simplifies the installation process, as merchants don't need to navigate to the theme editor, find the block, and then manipulate it. Instead, your app does the work for them. Merchants can preview blocks, so they control the content included in their storefront.

App Block Deep Links​

You can create deep links to add app blocks to:

• Any JSON template, such as the product template.
• A specific section by ID, such as an image-with-text section in the index.json template.

Example URL for App Block Deep Link

Your app needs to redirect merchants to the following URL with the appropriate query parameters:

https://<myshoplineDomain>/admin/theme/editor/editing/${templateAlias}?themeId=${themeID}&templateName=${templateName}&activateAppId=${uuid}/${handle}&target=newAppsSection

For example:

https://test.myshopline.com/admin/theme/editor/editing/Home?themeId=6486e09af9bbc878f5da89ff&templateName=templates/index.json&activateAppId=6bba0cf9-c86a-4d23-b71e-a144f95c2cc7/promotion-card&target=newAppsSection

App Block Deep Link Query Parameters

Adding an App Block to Any JSON Template

Use the following deep link format to add an App Block to a JSON template:

https://<myshoplineDomain>/admin/theme/editor/editing/${templateAlias}?themeId=${themeID}&templateName=${templateName}&activateAppId=${uuid}/${handle}&target=newAppsSection

For example, to add a Promotion Card to the last section on the homepage:

https://test.myshopline.com/admin/theme/editor/editing/Home?themeId=6486e09af9bbc878f5da89ff&templateName=templates/index.json&activateAppId=6bba0cf9-c86a-4d23-b71e-a144f95c2cc7/promotion-card&target=newAppsSection

Adding an App Block to a Specific Section by ID

Use the following deep link format to add an App Block to a specific section by ID:

https://<myshoplineDomain>/admin/theme/editor/editing/${templateAlias}?themeId=${themeID}&templateName=${templateName}&activateAppId=${uuid}/${handle}&target=sectionId:{sectionId}

For example, to add a Promotion Card to the image-with-text section on the homepage:

https://test.myshopline.com/admin/theme/editor/editing/Home?themeId=6486e09af9bbc878f5da89ff&templateName=templates/index.json&activateAppId=6bba0cf9-c86a-4d23-b71e-a144f95c2cc7/promotion-card&target=sectionId:1695572437385bfbbd3a

You can find the section ID in the JSON file of the template, such as the JSON data for the image-with-text section on the homepage:

{
  "sections": {
    "1695572437385bfbbd3a": {
      "type": "image-with-text"
    }
  },
  "order": [
    "1695572437385bfbbd3a"
  ]
}

App Embed Block Deep Links​

You can create deep links to directly activate App Embed Blocks in the theme.

Example URL for App Embed Block Deep Link

Your app needs to redirect merchants to the following URL with the appropriate query parameters:

https://<myshoplineDomain>/admin/theme/editor/editing/${templateAlias}?themeId=${themeID}&templateName=${templateName}&activateAppId=${uuid}/${handle}

For example:

https://test.myshopline.com/admin/theme/editor/editing/Home?themeId=63abc8fcf8a25d2d8854de5a&templateName=templates%2Findex.json&activateAppId=ac5292dd-7a66-41a4-b69f-5a163da0a421%2Fback-to-top

App Embed Block Deep Link Query Parameters

Performance improvement recommendations​

All files in the assets/ directory are effortlessly delivered via SHOPLINE's CDN, ensuring fast and reliable access. To enhance the performance of your theme app extension, consider the following recommendations:

• Reference your asset files by using the schema attributes javascript and stylesheets, or the Handlebars URL helpers asset_url and asset_img_url.
• For app embed blocks, load the corresponding scripts only on the pages where these blocks need to be displayed. This practice helps you to avoid unnecessary script loading, thereby improving the page’s loading speed and overall performance.

File and Content Size Limits​

When you push to the draft extension version, SHOPLINE validates the theme app extension. If the content exceeds mandatory limits, the extension fails validation and won't update. The table below shows the limits for theme app extensions:

Limitations​

The following pages and objects cannot be used with theme app extensions.

Pages​

Theme App Blocks and App Embed Blocks cannot be rendered on checkout pages. This includes all pages displayed when a customer initiates checkout, such as contact information, shipping methods, payment methods, and order status.

Handlebars Objects​

Theme app extensions do not have access to the following Handlebars objects:

• content_for_header
• content_for_layout
• content_for_footer
• section