Extensions from the theme (theme extensions)

What are theme extensions?

Theme extensions are extra fields that your theme makes available on products, categories, landing pages, static pages and blog posts, among other things. The theme developer defines the fields and as a store owner you fill them in directly in the admin, for example on the product edit page.

Typical examples are a field for a YouTube video ID, a badge with text and color, or a list of features with title, description and icon. The fields are automatically displayed in admin under the Extensions section from your theme, and the data you enter is used by the theme to display additional content in the online shop.

For store owners: How to use the extensions

When editing a product, you'll find the extensions in an accordion section called Extensions, from your theme. Click on the section to expand it. Here you will see the fields that the theme has defined, grouped by category (e.g. "Video Settings", "Badge Settings", etc.).

Fill in the fields as needed. Some fields are simple text fields, others are color selectors, image uploads or checkboxes. Each field typically has a title and optionally a description explaining what it is used for.

When you save the product, the extension data is saved and the theme uses it to display the relevant content in the webshop. For example, a filled-in YouTube ID will typically display a video player on the product page.

Supported field types

Theme extensions support a wide range of field types:

• text - A simple text field for short values (e.g. a video ID or badge text).
• richtext - An HTML editor with formatting options for longer texts with bold, italics, links, etc.
• longtext - A large text field (textarea) for longer texts without HTML formatting.
• number - A number field for numeric values.
• bool - A checkbox for yes/no values (e.g. "Show badge" or "Pickup only").
• color - A color picker to select colors visually (e.g. background color for a badge).
• list - A dropdown menu with predefined options.
• multi - Multiple checkboxes to select multiple options simultaneously.
• image - Upload a single image.
• images - Uploading multiple images (e.g. a gallery).
• date - A date picker.
• datetime - A date and time picker.
• repeater - Repeater fields that allow you to add a dynamic number of groups of fields (see separate section below).

For theme developers: Defining extension fields

Extension fields are defined in JSON files in the theme's extensions/folder. The file is named after the type of object the fields apply to:

• extensions/product.json - Products
• extensions/category.json - Categories
• extensions/landing_page.json - Landing pages
• extensions/static_page.json - Static pages
• extensions/blog_post.json - Blog posts

The JSON file is an array of groups, where each group has a name and a list of fields. Here is an example:

[ { "name": "Video Settings", "fields": [ { "title": "YouTube Id", "description": "Enter YouTube Video ID", "id": "youtube_id", "type": "text" } ] }, { "name": "Badge", "fields": [ { "title": "Badge - Text", "id": "badge", "type": "text" }, { "title": "Badge - Background color", "id": "badge-bg", "type": "color", "default_value": "#fef3c7" }, { "title": "Badge - Text color", "id": "badge-color", "type": "color", "default_value": "#92400e" } ]

Each field supports these properties:

• id (required) - Unique ID, used to retrieve the value in templates.
• title (required) - Label displayed in admin.
• type (required) - The field type (see list above).
• description - Help text displayed below the field.
• placeholder - Placeholder text in the input field.
• default / default_value - Default value.
• options - Options for list and multi types (object with key/value pairs).

For theme developers: Using extension data in templates

In Smarty templates, extension data is retrieved with the getExtensionValue('field_id') method. The method is available on products, categories, landing pages, static pages and blog posts.

Simple text value:

<{$product->getExtensionValue('youtube_id')}>

Conditional display (bool):

<{if $product->getExtensionValue('show_badge')}> <span style="background:<{$product->getExtensionValue('badge-bg')}>; color:<{$product->getExtensionValue('badge-color')}>>"> <{$product->getExtensionValue('badge')|escape}> </span> <{/if}

Simple image:

<{if $img = $product->getExtensionValue('img')}> <img src="<{$img->getSrc(400, 400, 'fit')}>"> <{/if}>

More images (gallery):

<{foreach $product->getExtensionValue('gallery') as $image}>> <img src="<{$image->getSrc(200, 200, 'box')}>"> <{/foreach}>

Date with formatting:

<{$product->getExtensionValue('release_date')|date_format:'%d/%m/%Y'}>

Repeat fields (repeater)

Repeater fields allow you to add a dynamic number of groups of fields. This is useful for e.g. a list of features, specifications or benefits of a product, where each item can have its own title, description and possibly an icon.

JSON definition of a repeater field:

{ "title":"Features", "id":"features", "type":"repeater", "field_title":"Feature", "description":"Add features to product", "fields": [ { "id":"title", "type": "text", "title": "Title", "placeholder": "Ex: Waterproof" }, { "id": "description", "type": "longtext", "title": "Description" }, { "id": "icon", "type": "image", "title": "Icon" } ] }

Repeater fields have these additional properties:

• fields - An array of subfields (supports text, richtext, longtext, number and image).
• field_title - The title displayed for each element in admin (e.g. "Feature").

In the admin, repeater fields are displayed as cards that can be added, deleted and moved via drag-and-drop. As a store owner, you click the "Add" button to create a new element and fill in the subfields.

Using repeater data in templates:

<{foreach $product->getExtensionValue('features') as $feature}> <h3><{$feature.title|escape}></h3> <p><{$feature.description|escape|nl2br}></p> <{if $feature.icon}> <img src="<{$feature.icon->getSrc(64, 64, 'fit')}>"> <{/if}> <{/foreach}>

Extensions for other object types

Extensions don't only work on products. The theme can define extension fields for multiple object types. The getExtensionValue() method is available on all supported objects:

• Categories - Defined in extensions/category.json. Use: $category->getExtensionValue('field_id')
• Landing pages - Defined in extensions/landing_page.json. Use: $landing_page->getExtensionValue('field_id')
• Static pages - Defined in extensions/static_page.json. Use: $page->getExtensionValue('field_id')
• Blog posts - Defined in extensions/blog_post.json. Use: $blog_post->getExtensionValue('field_id')

The JSON structure and field types are identical for all object types.

AJAX filtering with extension fields

Products can be filtered by extension values via AJAX filtering. This allows you to build filters in the webshop based on theme-specific fields.

The syntax uses extension. as a prefix in the URL parameters:

?extension.youtube_id=abc123 ?extension.show_badge=1

This allows theme developers to build advanced filtering experiences tailored to the needs of each online store.

Do you have questions about theme extensions? Contact us at support@shoporama.dk.