Introduction

Summary

Theme extensions are a powerful feature of our app, designed to allow you to add metafields as custom blocks to your storefront. They are compatible with all Online Store 2.0 themes, making implementation easier, giving you more flexibility and allowing you to control exactly how your content appears. All without coding. 


This lets you easily customize product pages and other templates. For example, if you prefer not to edit the theme code, you can simply add a theme extension instead. 


This article will guide you through the basics of using theme extensions and how to get started.


Available Extension Types

At this point, our app offers the following theme extensions:

1. Plain Text

2. Text

3. Reference

4. Link

5. Rating

6. Color

7. Date

8. Product Variant Text

9. Product Variant Link


Adding a Theme Extension

Adding an extension block to your theme's template is a consistent process across all our extension types. So, the steps below apply to all of our Theme Extensions. You will perform these steps directly within the Shopify Theme Editor.

Steps (via Shopify Admin):

  1. Navigate to your Shopify Theme Editor (Online Store > Themes > Customize).

  2. Select the specific location (for example, a product page) where you want to display the metafield content.

  3. Add a new block and select the specific Theme Extension block provided by our app.

  4. In the block's settings panel, you will input the correct metafield details as defined in your Shopify Admin.

Example Setup:

  • When configuring the block, you must refer to the exact Namespace and Key you have set up in the Shopify admin.

  • Example: If your metafield is defined with namespace = metafields_master, key = plain_text, and type = Single Line Text, you will enter those exact values into the block settings.


Common Parameters for Configuration

All theme extension blocks use the following parameters to locate and display your data:

  • Namespace (Required)

    • Purpose: This is the primary grouping mechanism for your metafields.

    • Examples: metafields_master

  • Key (Required)

    • Purpose: This is the unique identifier for a specific metafield within its assigned Namespace.

    • Examples: size_chart, release_date

  • Use global (shop) value

    • Purpose: If checked, the extension will pull the value from a Shop metafield (a value that applies to the entire store) rather than the local object (like a specific product or collection).

  • Use global (customer) value

    • Purpose: If checked, the extension will pull the value from a Customer metafield (data associated with the logged-in customer).


Extension Type Details

1) Plain Text

The Plain Text extension is the simplest way to display your metafield content. It displays the raw metafield value without any additional formatting. 

  • Supports: All standard metafield types.

Presentation & Formatting:

  • Prefix/Postfix: Add custom text, symbols, or units before (Prefix) or after (Postfix) the displayed metafield value.


2) Text

The Text extension is used for displaying textual or numeric values. It provides additional options for formatting the content for a cleaner presentation. It’s useful when working with lists or units.

  • Supports: Single Line, Multi-line, Rich Text, Integer, Decimal, Lists, Dimension, Volume, Weight, Money, and String metafield types.

Presentation & Formatting:

  • List Type: If your metafield is a list, this controls how list values are displayed. The provided options are: Comma (default), Bullets, and Numbers.

  • Display Units: Ment to show the units defined by the metafield type. This applies to Dimension, Volume, and Weight.

  • Prefix/Postfix: Add text before or after the value.


3) Reference

The Reference extension is designed to display references (like related products or collections) within customizable cards directly on your storefront.

  • Supports: Product, Variant, Collection references & lists. 

Presentation & Formatting:

  • Card Text Color: Sets the color of the text displayed on the card.

  • Card Background: Sets the background color of the card.

  • Template: Defines the layout of the referenced items: Grid (default), Slider, or List.

  • Desktop and Mobile Columns: Set the number of items shown per row on desktop (default: 3) and mobile (default: 1).

  • Space Between Cards: Controls the spacing around each item card.

  • Card Corner Radius: Set the rounding of item corners (default: 8px).

  • Show Vendor: Toggles whether the product vendor is displayed.

  • Show Compare Price: Toggles to display these details on the cards.

  • Text Size: Controls the size of the text. The options are Small, Medium, and Large.

  • Aspect Ratio: Defines the shape of the displayed image 

  • Link Settings: Option to open the linked product/collection in a new tab.

  • Slider Settings: You can customize the appearance of your slider by adjusting the Primary and Secondary colors, choosing your preferred Navigation style (either Background or Icon), and selecting a Pagination style such as Circle, Square, Bar, or Line.

  • Prefix/Postfix: Add text before or after the entire block content.


4) Link

The Link extension is designed to display various types of links, URLs, files, and references dynamically on your storefront.

  • Supports: Links, URLs, Files, Products, Variants, Collections, Pages and lists. 

Presentation & Formatting:

  • Link Target: Controls whether the link opens in the Same tab or a New tab.

  • Label: Allows you to define a custom, static text label for the link.

  • List Type: If your metafield is a list of links, this controls the visual style, such as Comma, Bullets, and Numbers.

  • Prefix/Postfix: Add text before or after the link text.

Below is an example of when you have a list of links. 


5) Rating

The Rating extension allows you to visually display ratings using customizable icons and colors.

  • Supports: Rating, and Rating list.

Presentation & Formatting:

  • Icon Style: Selects the visual element used for the rating.

  • Icon Size / Spacing: Control the dimensions and distance between icons.

  • Active Color / Inactive Color: Set the color for filled icons (Active, default: #FDCC0D) and empty icons (Inactive, default: #CDCDCD).

  • Show Rating Details: Toggle to show the numeric rating in "x/5" format.

  • Heading: Add custom heading text above the rating icons.


6) Color

The Color extension is specifically designed to display color metafield values as visual swatches.

  • Supports: Color, and Color list.

Presentation & Formatting:

  • Size: Set the size of the color swatch square (default: 20px).

  • Radius: Controls the rounding of the swatch corners (default: 50% for a perfect circle).

  • Spacing: Set the distance between swatches in a list (default: 4px).

  • Prefix/Postfix: Add text before or after the swatches.


7) Date

The Date extension ensures that Date or Date & Time metafields are displayed in a clean, readable format of your choice.

  • Supports: Date, Date list, Date & time, Date & time list.

Presentation & Formatting:

  • Format Options: Allows you to select from various predefined display formats.

  • List Type: Controls how list values are displayed (Comma, Bullets, Numbers).

  • Prefix/Postfix: Add text before or after the date block.


8) Product Variant Text

This extension functions identically to the Text Extension, but it is used specifically for pulling data stored in Product Variant Metafields.

Presentation & Formatting:

  • Use Product Value as Default: When the setting is enabled, if a specific variant metafield is missing, the app will automatically fall back to the product-level metafield. This ensures that your storefront still displays consistent and complete information, even if certain variants don’t have their own custom values defined.


9) Product Variant Link

This extension works just like the standard Link theme extension, but with one key difference. The values are pulled directly from your variant metafields instead of product metafields. 

Presentation & Formatting:

  • Use Product Value as Default: Option ensures that your storefront always displays a link, even when a specific variant doesn’t have a metafield value defined. When this option is enabled, if the variant metafield is missing, the app will automatically fall back to the product-level metafield.