Skip to content

theme.xml Format

Jump to bottom
John Stray edited this page Jul 12, 2022 · 1 revision

This document explains the format for the theme.xml file that GetSimple CMS theme developers can include with their themes to make it compatible with this plugin and therefore more configurable by end users.

The file consists of 4 main parts:

  • The Metadata section - This is used to describe some basic information about the theme, such as it's name and author
  • The Config Options section - This is used to define options which allow the theme to be configured
  • The Custom Fields section - This is used to enable the use of Custom Fields available to pages of the site
  • The Blog Fields section - Same as above, but specifically for use with Blog plugins such as SimpleBlog

An example of the theme.xml file with all possible options is provided within the repository.

The Root Element

Since this is an XML file, it will start with the root element in which other elements will be a child of.

<?xml version="1.0" encoding="utf-8"?>
<theme>
    ...
</theme>

The Metadata section

This section of the file is used to describe the basic metadata of the theme, such as it's name and author. Fields here can be used as basic strings, or can be internationalized by using an array of strings with the language code as the key. Languages are only shown when GetSimple has the relevant language currently supported and enabled, otherwise English (en_US) is used as default. The following fields are currently supported:

Name

The name of the theme. This field can be internationalized.

<name>My Great Theme</name>

or

<name>
    <en_US>My Great Theme</en_US>
    <de_DE>Mein großes Thema</de_DE>
</name>

Description

A description of the theme, possibly with some useful information. This should be kept at a length of about 255 characters. This field can be internationalized.

<description>The quick brown fox jumped over the lazy dog</description>

or

<description>
    <en_US>The quick brown fox jumped over the lazy dog</en_US>
    <de_DE>Der schnelle braune Fuchs sprang über den faulen Hund</de_DE>
</description>

Author

The name of the theme's author. This field is not internationalized and should represent the author's actual name

<author>John Stray</author>

Author's URL

A URL pointing to the author's website, or to the theme projects page / documentation page. This field is internationalization allowing for a link based on the selected language.

<author-url>https://johnstray.com/index.php?id=my-great-theme</author-url>

or 

<author-url>
    <en_US>https://johnstray.com/index.php?id=my-great-theme</en_US>
    <de_DE>https://johnstray.com/index.php?id=my-great-theme&lang=de_DE</de_DE>
<author-url>

Version

The version of the theme. This field is a basic string of text only representing the version of the theme.

<version>1.0.0-alpha</version>

The Config Options Section

The config options section provides an array of options for the theme that an end-user can configure. These will show up on the 'Themes' tab within the GetSimple CMS admin area. The config options section contains multiple child items, each relating to each configurable option. There are multiple input type to choose from, refer to the list of field types later in this document to see what is supported.

The Config Options section is a child of the root element and itself contains multiple child elements. The key or tag for each child option becomes the field identifier which can later be obtained from within the theme templates.

<config>
    <my-conf-opt>
        ...
    </my-conf-opt>
    <another-opt>
        ...
    <another-opt>
<config>

The Custom Fields Section

The custom fields section provides an array of options that allows an end-user to add additional metadata on a per-page basis which can then be used within the theme template. These will show up in the metadata section of the page editor.

The Custom Fields section is a child of the root element which itself contains multiple child elements. The key or tag for each child option becomes the field identifier which can later be obtained from within the theme templates.

<customfields>
    <my-data-opt>
        ...
    </my-data-opt>
    <another-field>
        ...
    </another-field>
</customfield>

The Blog Custom Fields Section

This section works in the same way as the Custom Fields section with the exception that it is specifically for blog posts where a supported Blog plugin is used, such as the SimpleBlog plugin. Where these options will show up depends upon which blog plugin is being used. In the case of the SimpleBlog plugin, they will show up in an extra tab in the metadata section on the post editor page.

The Blog Custom Fields section is a child of the root element which itself contains multiple child elements. The key or tag for each child option becomes the field identifier which can later be obtained from within the theme templates.

<blogfields>
    <my-data-opt>
        ...
    </my-data-opt>
    <another-field>
        ...
    </another-field>
</blogfield>

Supported Fields

Each of the 3 above section all support the following format for a field. Some elements are i18n-able, usually if it's an element used to show a string of text in the admin section. Where an element is i18n-able, it can also be used as a simple single string of text instead.

<my-data-opt>

    <!-- Display Label for the option (i18n-able) -->
    <label>
        <en_US>My Data Option</en_US>
        <de_DE>Meine Datenoption</de_DE>
    </label>

    <!-- Hint Text - shown below the label (i18n-able) -->
    <hint>
        <en_US>Short text describing what this field is for</en_US>
        <de_DE>Kurzer Text, der beschreibt, wozu dieses Feld dient</de_DE>
    <hint>

    <!-- Type - Determines the type of field to show, must be 1 of:
         text, number, tel, url, color, date, dropdown, radio, checkbox -->
    <type>text</type>

    <!-- Default - The default value of the field, can be empty -->
    <default>default-value</default>

    <!-- Options array - used for dropdown, radio and checkbox type fields
         each is tag is a possible value, and the string in between is the display text.
         Options are i18n-able -->
    <options>
        <opt-value-a>
            <en_US>Option Value A</en_US>
            <de_DE>Optionswert A</de_DE>
        </opt-value-a>

        or

        <opt-value-b>Option Value B</opt-value-b>
    </options>

    <!-- Pattern (optional) - Browser validation regex, eg. <input pattern="" />
         Applies to: text, tel and url type options -->
    <pattern> ... </pattern>

    <!-- Regex (optional) - A PHP preg_match compatible regex string to validate options serverside
         Applies to: text, number, tel, url, color and date type options -->
    <regex> ... </regex>

    <!-- Range (optional) - A range in the format of min,max,step 
         Applies to: number and date type options -->
    <range>0,100,0.01</range>
    <range>1970-01-01,2032-12-31,1</range>

    <!-- Size (optional) - The min and max character length of the value
         Applies to: tel, url -->
    <size>8,10</size>

</my-data-opt>

Clone this wiki locally