Regarding the themes in a MyCashflow online store, you can define their settings and supported features in the configuration file theme.xml. In this article, we will look at the contents of the configuration file and how it works in a theme.

If the configuration file is missing from a store theme, the theme cannot be used in an online store.

The configuration file is an XML file from which, for example, certain Interface tags can read the information they need. Certain features (e.g. gift cards and product filters) need to be enabled in the theme using the settings file.

Place the configuration file inside the root directory of the theme (for example, themes/shop/THEME-NAME/theme.xml).

The structure of the configuration file

A configuration file comprises 4 root-level elements:

  • <Version/>: version number for the theme
  • <Settings/>: general settings concerning the theme
  • <Features/>: features supported by the theme
  • <ImageSizes/>: image sizes to be used in various contexts (e.g. images on product pages and product lists)
  • <ThemeSettings/>: custom, theme-specific settings

Below, you can see an example of the basic structure of a configuration file:

<?xml version="1.0"?>
<Theme>
  <Version>1</Version>
  <Settings>
    ...
  </Settings>
  <ImageSizes>
    ...
  </ImageSizes>
  <Features>
    ...
  </Features>
  <ThemeSettings>
    ...
  </ThemeSettings>
</Theme>

In the following chapters, we will take a closer look at the contents of the elements.

Versioning

The <Version/> element allows you to keep track of the development of the theme. You can update the version number each time you change the theme and also create a separate readme.md file to describe the changes by version.

Based on the version, the output of the {MinifyJS} and {MinifyCSS} tags also includes the version parameter v=x. With this parameter, changes made to the CSS/JavaScript files in the theme will not be cached, which facilitates editing the theme.

<?xml version="1.0"?>
<Theme>
  ...
  <Version>1</Version>
  ...
</Theme>

Metadata

The <Doctype standard="HTML5/XHTML"/> field in the settings defines the HTML document type for every page in a theme. The value of the field can be HTML5 or XHTML (default).

The document type definition is included in a theme with the {Doctype} tag, which prints the complete document type definition (e.g. <!doctype html>).

<?xml version="1.0"?>
<Theme>
  ...
  <Settings>
    <Doctype standard="HTML5"/>
  </Settings>
  ...
</Theme>

Images

With the <NoImage file="i/noImage.jpg"/> field in the settings, you can set a default product image for all products that have no dedicated product images. Product image tags, such as {ProductImages}, will show the image defined in the field's file attribute.

The location of the image needs to be defined in relation to the /files folder in the online store's file directory. In the example below, the noImage.jpg image is located in a subfolder called i within the files folder.

<?xml version="1.0"?>
<Theme>
  ...
  <Settings>
    <Images>
      <NoImage file="i/noImage.jpg" />
    </Images>
  </Settings>
  ...
</Theme>

Additionally, with the <ImageSizes/> element you can define a suitable image size for various purposes:

  • <Mini/>: used for thumbnails in the shopping cart, for example
  • <List/>: used for products on product lists
  • <Normal/>: used for product images on product pages
  • <Big/>: used for product image enlargements
  • <OpenGraph/>: used for images included in OpenGraph metadata (these should be large)
  • <BrandList/>: used for brand logos included in navigation and on lists
  • <BrandNormal/>: used in the {ProductBrand} tag on the product page
  • <CampaignImage/>: used for campaign images in campaigns as well as product categories and brands
  • <CheckoutLogo/>: used at checkout for the logos of shipping and payment methods
<?xml version="1.0"?>
<Theme>
  ...
  <ImageSizes>
    <Mini width="32" height="32"/>
    <List width="162" height="162"/>
    <Normal width="258" height="258"/>
    <Big width="900" height="600"/>

    <OpenGraph width="1500" height="1500"/>
    
    <BrandList width="32" height="32"/>
    <BrandNormal width="162" height="162"/>
    
    <CampaignImage width="383"/>
    <CheckoutLogo width="270" height="90"/>
  </ImageSizes>
  ...
</Theme>

Checkout

The checkout types supported by the theme are defined in the <Checkout/> section in the theme properties.

The <SinglePage supported="true/false" /> and <MultiPage supported="true/false"/> settings define the available checkout types for the theme. For example, if there is <SinglePage supported="false"/> set in the configuration file, using the single-page checkout is not possible even if it has been selected in the version settings. In this case, the theme only has the multi-page checkout available. If the templates for the selected checkout are not included in the theme, the online store automatically uses the corresponding built-in checkout.

If both checkout types are available, you can select the type you want in the version settings. If no selection has been made in the version settings, the checkout is defined with the default="default" attribute.

<?xml version="1.0"?>
<Theme>
  ...
  <Features>
    <Checkout>
       <SinglePage supported="true" />
      <MultiPage supported="true" default="default" />
    </Checkout>
  </Features>
  ...
</Theme>

Tax-free prices

You can add support to the theme for the version-specific Show prices without VAT setting, allowing you to create a B2B store version of the online store without having to create a separate theme for the version.

Implement theme support for tax-free pricing by adding the <VatFree supported="true"/> setting to the <Settings> section in the theme settings. Also make sure that none of the tags showing the theme prices are using the includetax attribute.

<?xml version="1.0"?>
<Theme>
  ...
  <Features>
    <VatFree supported="true"/>
  </Features>
  ...
</Theme>

Setting tax-free prices does not work in PDF themes. If you want to display the prices without tax, you need to add the includetax: false attribute to all the price tags used in PDF themes.

Also read:

Product lists

In the theme settings, the <ProductList/> section defines the page sizes that are available in the pagination menu for product lists.

This setting only affects pagination tools for the product lists that use product filters.

A pagination menu is printed for product lists by the {PaginationLimit} tag.

For example, the setting below will allow the customer to choose how many products are shown per page on the product list, with three available options: 25, 50 or 100.

<?xml version="1.0"?>
<Theme>
  ...
  <Settings>
    <ProductList>
      <PageSizes>
        <PageSize>25</PageSize>
        <PageSize>50</PageSize>
        <PageSize>100</PageSize>
      </PageSizes>
    </ProductList>
  </Settings>
  ...
</Theme>

The maximum length of a product list is 100 products.

Gift cards

With the <GiftCards supported="true/false"/> setting, you can enable expanded support for gift cards in the online store.

When the <GiftCards/> setting is set to true

  • The {CartTotal} tag prints the cart subtotal including discounts
  • {CartOpenTotal} returns the open balance
  • There's no need for the customer to select a payment method at checkout if, after enabling a gift card, the order total is 0 €.

Using the value false

  • {CartTotal} prints the open balance (after a gift card has been applied)
  • {CartOpenTotal} does nothing because the tag is only enabled for the new gift cards
  • the customer must select a payment method at checkout even if there's nothing left to pay.

Learn more about the setting and its impact

<?xml version="1.0"?>
<Theme>
  ...
  <Features>
    <GiftCards supported="true" />
  </Features>
  ...
</Theme>

Product bundles

The <ProductBundles supported="true/false"/> setting in theme properties defines the implementation method for product bundles.

If the value is false (or if the setting is missing), the {ProductShortDesc} tag will include product bundles in the short product description. If the value is true, product bundles are not included in the product description, but a list of product bundles is displayed by the {ProductBundles} tag, which needs to be added to a suitable location within the theme.

Learn more about implementing product bundles in a theme

<?xml version="1.0"?>
<Theme>
  ...
  <Features>
    <ProductBundles supported="true" />
  </Features>
  ...
</Theme>

Custom theme settings

It is possible to add custom settings to the theme settings, which appear in the theme editor menu as WYSIWYG tools that can be managed by the user.

Also read:

The default theme of MyCashflow relies heavily on custom settings that are managed through a graphical user interface. You can install the theme and customize it as needed, or use it as a template when crafting a new theme.

Custom settings are defined in the <ThemeSettings/> section of the configuration file, the structure of which is described below:

<?xml version="1.0"?>
<Theme>
    ...
    <ThemeSettings>
        <SettingGroup label="custom_setting_group_1" description="custom_setting_1_group_description">
            ...
            <Setting type="boolean|select|color|integer" default="foo" name="foo" label="setting_1" description="setting_1_description"/>
        </SettingGroup>
    </ThemeSettings>
    ...
</Theme>

Custom settings are used in the theme with the {Setting} tag. The tag prints values stored in different settings based on the name attribute of the settings.

It is possible to group settings using the <SettingGroup/> element. With groups, you can gather related settings together to help the theme user navigate the menu.

Multilingual names and descriptions can be defined for settings and setting groups, which are implemented together with the theme.xml file and theme translation files.

Below, the elements used to define custom settings and their possible attributes are discussed.

  • <SettingGroup/>
    • label (required): The name of the settings group that appears in the settings menu.
    • description: Description of the setting group, which appears in the settings menu.
  • <Setting/>
    • type (required): The type of setting that determines the control element visible in the settings menu and guides its use in the theme. Possible values:
      • boolean
      • select

        If the value is select, <Option value="foo" label="Bar"/> elements must be added inside the <Setting/> element, which define the options available for selection in the list (read more about implementing a select list).

      • integer: With number-type settings, the following optional attributes are also available:
        • min: minimum value
        • max: maximum value
        • step: the amount added or removed with one press of the number field control arrow.
        • unit: unit (e.g. px)
      • color
    • default (required): The default value, whose possible content depends on the type attribute. It determines how the setting works in the theme when the theme user has not entered any value for it.
    • name (required): The name of the setting. Used in the {Setting} tag to identify the setting when it is used.
    • label (required): The name of the setting that appears in the settings menu.
    • description: Description of the setting that appears in the settings menu.

Sample configuration file

If you are developing your own theme, you can copy the attached configuration file directly to the root directory of your theme under the name theme.xml and modify it according to your needs.

<?xml version="1.0"?>
<Theme>
  <ImageSizes>
    <Mini width="80" height="80" />
    <List width="180" height="180" />
    <Normal width="600" height="600" />
    <Big width="1200" height="1200" />
  </ImageSizes>
  <Features>
    <Checkout>
      <SinglePage supported="true" default="default" />
      <MultiPage supported="false" />
    </Checkout>
    <GiftCards supported="true" />
    <ProductBundles supported="true" />
    <ProductListFilters supported="true" />
  </Features>
  <Settings>
    <Doctype standard="HTML5" />
    <ProductList>
      <PageSizes>
        <PageSize>25</PageSize>
        <PageSize>50</PageSize>
        <PageSize>100</PageSize>
      </PageSizes>
    </ProductList>
  </Settings>
</Theme>