Project Theme Configurator

The Configurator Extension offers an interface to set variuos configuration options from withing the TYPO3 backend. Values get stored in individual .json-files and can be understood as themes. A theme file basically holds all values to the defined options.

The interface-configuration.json file

The whole editor interface, including all possible fields to store values in, is defined inside the interfaceConfiguration.json. The structure of this file is as follows:

Tabs

The first level of the file divides all data according to the tabs in configurator. Right now there are five tabs and each of them has a top-level key in the json-file.

{
    "typoscript": [],
    "frontend": [],
    "configuration": [],
    "customCssAndJs": [],
    "colorSets": []
}

Panels

Inside a tab, you can structure your fields inside panel. A panel is a visually separated space inside the interface that can have its own title and description. You can define as many panels as you need.

{
    "frontend": [
        {
            "name": "sharer",
            "label": "Social Media Accounts",
            "description": "If you use the social media share buttons, you can configure the different accounts for them here.",
            "type": "styles",
            "columnsSize": "6",
            "items": []
        }
    ]
}

A panel can have the following attributes:

name

A unique key to identify the panel programatically

label

A string that will be displayed as the panel's title

description

A string that will be displayed as the panel's description

type

An arbitrary field right now. Just define your own types to structure your panels.

columnsSize

This field can be used to control the layout of the editor. Usually, a panel will divide fields into three columns. By setting this field, you can override that behavior. You can set any number between 1 and 12, which will define how many columns (on a 12 column grid) each field inside the panel will take up.

items

This array will hold all fields that belong to this panel.

Fields

A field is the entity that in the end will hold your data. You can have as many fields inside a panel as you want. Just add them to the item-array of a panel.

{
    "frontend": [
        {
            "name": "sharer",
            "label": "Social Media Accounts",
            "description": "If you use the social media share buttons, you can configure the different accounts for them here.",
            "type": "styles",
            "columnsSize": "6",
            "items": [
                {
                    "name": "plugin.tx_project_base.config.pageTitle",
                    "label": "Page Title",
                    "description": "",
                    "access": "public",
                    "storage": "tsConstants",
                    "dataTransformation": ""
                }
            ]
        }
    ]
}

A field has multiple attributes that define its behavior.

name

The variable name your value will be stored in. This directly maps the variable name of your storage type. So, e.g. if you have a tsConstant field of the name lib.foo, your TypoScript constant will be lib.foo as well.

label

A string that will be used as the form field label.

description

A string that will be displayed as the description of your field.

access

Defines who can access this field. You can either set it to public, or the ID of a TYPO3 usergroup. If you set a usergroup, only users that are part of that group will be able to see this field.

storage

The storage attribute defines the way you field will be persisted. The following storage methods can be used:

  • tsConstants: Your field will be stored as a TypoScript constant.
  • tsSetup: Your field will be stored as TypoScript setup. You can use multiline strings here.
  • customProperty: Your field will be availabel as a CSS custom property.
  • localConfiguration: Your field will be stored in the LocalConfiguration Array.

type

The type of your field defines how your input will look like. The default type is text which will just display a single-line text input. But there are a lot more:

  • font: Displays a font-selector, based on the available font-families.
  • font-source: Displays a multi-line field that accepts font-names, as well as links to webfonts
  • number: A numeric input. In addition, you can set the attribute unit on your field to define the unit of your number (e.g. px).
  • image: A file-upload with image preview.
  • favicon: Basically the same as Image, but it displays your image in different resolutions.
  • color: Displays a color picker.
  • editor: Displays a code-editor with syntax-highlighting.
  • checkbox: Displays a toggle, which will set your value to 0 or 1. This attribute is especially useful in addition with the controls attribute. You can use this to activate/deactivate any other field, depending on your checkbox.
  • colorSet: Displays a color-set-selector, based on the sets available in the colorSets array.

unit

Useful in combination with type: number. Defines the unit of a field and will be appended to the value.

controls

Useful in combination with type: checkbox. You can set this attribute to the name of any other field and then use the checkbox to turn it off and on.

filename

If your field contains user uploaded data, you can specify a filename which will be used instead of the original one.

dataTransformation

You can specify a transformation that will be applied to your value before saving it.

Data Transformations

For some fields, you will need to transform the raw data you get from the interface. With Data Transformations, you can do exactly that. Transformations are defined inside the DataTransformationService. Right now, there are two transformations available:

  • WebFontDefinitions: will parse links to webfont-stylesheets and return the actual webfont definitions.
  • FileUpload: will handle file uploads. This is meant to be used with fields that contain user uploaded data. The transform will move the userdata to the upload directory and save it there. It will append a random string to the filename, to ensure cache-busting and delete previously uploaded data that will have no more reference.
  • ColorToRgb: will convert a hex color value to a comma-separated list of RGB values as string. This way we can use rgba() with a CSS variable's color value.

Color Sets

How to add Color Sets

New Color Sets can be added by touching the following files:

  1. project_theme_configurator/Resources/Private/Backend/Partials/Form/ColorSet.html
    • Add the new color set to foreach-loop's array
  2. config/website-base-configuration/interface-configuration.json
    • Add the new set to the colorSets array

How to add Color Set properties

Color Sets have multiple properties which can be extended by touching the following files:

  1. project_theme_configurator/Classes/Service/CssService.php
    • Add the new property to the COLOR_SET_PROPERTIES array
  2. config/website-base-configuration/interface-configuration.json
    • Add the new property to the colorSets array