Theme settings for products and pages (theme extensions)

What are Theme Settings for products and pages?

Theme extensions are additional fields that your theme makes available on products, categories, landing pages, static pages, and blog posts. In the admin panel, these fields are located in the Theme Settings tab, which was previously called “Extensions from your theme.” The theme developer defines the fields, and as a store owner, you fill them out directly in the admin panel—for example, on the product edit page.

Typical examples include a field for a YouTube video, a badge with text and color, add-ons for the product, or a list of attributes with a title, description, and icon. The theme uses the data you enter to display additional content in the online store.

For Store Owners: How to Use Theme Settings

When editing a product, you’ll find the Theme Settings tab between the Fields and Internal Search tabs, and as a shortcut in the right-hand menu. Click the tab to expand it. The fields are organized into groups with headings, such as Video, Badge, and Add-ons. On categories, static pages, landing pages, and blog posts, the tab is located directly below General.

Fill in the fields as needed. Some fields are simple text fields, while others are color pickers, image uploads, or checkboxes. Each field has a title and typically an explanation describing its purpose.

When you save, the fields are saved along with the product or page, and the theme uses them to display the relevant content in the online store. For example, a filled-in YouTube video ID in Montana displays a video in the product’s image gallery. Text fields on products are also included in the store’s internal search, unless the theme developer has opted out of this feature.

You can also use product fields on a landing page. Select the “Extended Product Field” rule, and the landing page will display the products that have a specific value in that field.

Theme Settings in Montana and MontanaB2B

In Montana and MontanaB2B, the fields are in Danish and explained directly in the admin panel. For products, there are three groups:

• Video: the “YouTube Video ID” field. The ID is the last part of the YouTube link, so in youtube.com/watch?v=dQw4w9WgXcQ, the ID is dQw4w9WgXcQ. The video appears in the product’s image gallery.
• Badge: the Badge Text, Badge Background Color, and Badge Text Color fields. The badge appears as a label on the product image, e.g., “New” or “Online Only.”
• Add-ons: the Product IDs for add-ons field. Enter the IDs of the products the customer can add to the cart along with this product, separated by commas, e.g., 123,456. The product ID appears in the address bar when you edit a product, and add-ons with variants have their own variant selector. Read more in Add-ons on the product page.

Fields that did not function as intended have been removed from Montana and MontanaB2B:

• Product comment field. If the customer needs to enter text for the item—such as for an engraving—use customer input on products instead.
• "Pickup Only," which only displayed a stock status on the product page and did not hide the other shipping options at checkout.
• Hide the bundle display and hide price tables for volume discounts and variants.
• All fields on categories, static pages, blog posts, and landing pages. As a result, Montana and MontanaB2B no longer display the “Theme Settings” tab there.

Data you previously saved in these fields will not be deleted, but it will no longer appear in the admin panel, and the theme will not use it. If you use your own customized copy of Montana, your fields will remain unchanged, as Shoporama does not modify stores’ own themes. Other themes, such as Delaware, DelawareDK, California, and Alaska2, have their own fields.

Supported Field Types

Theme settings support a wide range of field types:

• text: a single text field for short values (e.g., a video ID or badge text).
• richtext: an HTML editor with formatting options for longer texts, including bold, italics, links, and more.
• longtext: a large text field (textarea) for longer texts without HTML formatting.
• number: a numeric field for numerical values.
• bool: a checkbox for yes/no values (e.g., “Show badge”).
• color: a color picker for visually selecting colors (e.g., background color for a badge).
• list: a dropdown menu with predefined options.
• multi: multiple checkboxes for selecting multiple options at once.
• image: Upload a single image.
• images: Upload multiple images (e.g., a gallery).
• date: a date picker.
• datetime: a date and time picker.
• repeater: repeatable fields that allow you to add a dynamic number of groups of fields (see separate section below).

For theme developers: Defining fields

Fields are defined in JSON files in the theme’s `extensions/` folder. The file is named according to 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

If the file does not exist or contains only an empty array, [], the theme has no fields for that type, and the Theme Settings card will not appear in the admin panel. For example, Montana and MontanaB2B have empty files for categories, landing pages, static pages, and blog posts.

The JSON file is an array of groups. Each group has a name, an optional description, and a list of fields. The name appears as the header in the card, and a description appears after the name. Here is an excerpt from Montana:

[
    {
        "name": "Video",
        "description": "",
        "fields": [
            {
                "title": "YouTube video ID",
                "description": "The ID from the YouTube link. In youtube.com/watch?v=dQw4w9WgXcQ, the ID is dQw4w9WgXcQ. The video appears in the product’s image gallery.",
                "id": "youtube_id",
                "type": "text"
            }
        ]
    },
    {
        "name": "Badge",
        "description": "",
        "fields": [
            {
                "title": "Badge text",
                "description": "Displayed as a badge on the product image, e.g., New or Online Only.",
                "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 the admin panel.
• type (required): the field type (see the list above).
• description: help text displayed below the field. Write this for the store owner so it’s clear what the field does in the store.
• placeholder: placeholder text in the input field.
• default: default value for text, longtext, richtext, number, date, and datetime.
• default_value: default value for "color." Without a default value, the color picker starts at black.
• options: Options for list and multi types (object with key/value pairs).
• searchable: applies only to products. Text, list, and multi-select fields are automatically included in the store’s internal search. Set "searchable": false to exclude a field.

The default value is entered in the admin panel and is not saved until the product or page is saved. Until then, the field has no value in the templates, so make sure the theme also works when the field is empty.

For theme developers: Using data in templates

In Smarty templates, values are retrieved using the getExtensionValue('field_id') method. This method is available for products, categories, landing pages, static pages, and blog posts. If the field is empty, it returns false. A boolean field returns true or false, a number field returns an integer, an image field returns an image, and image and multi fields return a list.

Simple text value:

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

Conditional display (boolean):

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

Single image:

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

Multiple 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'}>

If you remove a field from the JSON file, the saved values will remain. The field will disappear from the admin panel and the REST API, but `getExtensionValue()` can still retrieve the value. Therefore, you should also remove any references to it in templates if you no longer want the field to have any effect.

Repeater Fields

Repeater fields allow you to add a dynamic number of groups of fields. This is useful, for example, for 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 the product",
  "fields": [
    { "id": "title", "type": "text", "title": "Title", "placeholder": "E.g.: 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 the admin panel (e.g., "Feature").

In the admin panel, repeater fields appear as cards that can be added, deleted, and moved via drag-and-drop. As a store owner, click the "Add" button to create a new item 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}>

Theme Settings for Other Object Types

The fields don’t just work on products. The theme can define fields for multiple object types, and the getExtensionValue() method is available on all supported objects:

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

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

For developers: REST API

The fields can also be read and written via the REST API in the `extension_data ` field for products, categories, blog posts, static pages, and landing pages. Only fields defined in the theme’s JSON file are included. This is useful when many products need to have the same field filled in.

AJAX Filtering with Extension Fields

Products can be filtered by their values using AJAX filtering. This allows you to build filters in the online store 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 individual online store.

Frequently Asked Questions

Where has “Extensions from your theme” gone on the product page?

The tab is now called Theme Settings and is located between the Fields and Internal Search tabs. The name has been changed everywhere: on products, categories, static pages, landing pages, and blog posts. The fields and your saved values are the same as before, unless your theme has removed a field.

I’m using Montana and can’t see “Theme Settings” on my categories. Is something wrong?

No. Montana and MontanaB2B only have fields on products, and the tab only appears when the theme has fields for that type of page. The fields on categories and pages have been removed because the theme didn’t use them for anything. What you had previously saved there will not be deleted.

We had set some products to “Pickup Only” in Montana. What happens now?

The field only displayed the text “Pickup Only” next to the stock status on the product page. It didn’t hide the other shipping options at checkout, so customers could still choose delivery. That’s why the field has been removed, and the text no longer appears. If an item is available for pickup only, please state this clearly in the description, and contact support@shoporama.dk if you have any questions about your shipping setup.

Where can I find the YouTube video ID?

Open the video on YouTube and copy the part of the URL that comes after “v=”. In youtube.com/watch?v=dQw4w9WgXcQ, the ID is dQw4w9WgXcQ. Paste only the ID, not the entire link. In Montana, the video appears in the product’s image gallery.

Can I fill out Theme Settings for multiple products at once?

In the admin panel, you fill out the fields for each individual product. If multiple products need the same settings—such as the same badge—you can do this via the REST API or with Claude if you ’re managing the store with AI. If you duplicate a product, the fields are carried over to the copy.

I removed a field from my extensions file. Is the data gone?

No. The values remain, but the field no longer appears in the admin panel or in the REST API. Templates can still read the value using `getExtensionValue()`, so be sure to remove any references to it in the theme as well. If you add the field again with the same ID, the old values will reappear.

What is the difference between Theme Settings and custom fields?

The fields in Theme Settings are predefined fields from the theme that include a title, an explanation, and a fixed position in the store. Custom fields are your own keys and values that you enter in the Fields card and that are only displayed when a theme or feed retrieves them. Read more in Extended Fields.

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