Themes

One of the most powerful features of Synergy is the ability to create themes. Themes are used to create distinctly separate UI's using a combination of modules and custom configuration, without modifying any source code.

A theme in Synergy is just a JavaScript object attached to the Window Object that will be read by your Synergy modules automatically.

Using themes requires you to create your modules using the Magic Method (as opposed to the Muggle Method)

Creating a Theme

Synergy recommends keeping your themes inside a themes directory that exists alongside the modules directory.

|-- modules
|   |-- Accordion
|   |   ...
|-- themes
|   |-- myTheme.json
|   |   ...

As a theme should contain no logic and just raw values, it's recommended to use a JSON file for your theme, though you can also use standard JavaScript.

themes/myTheme.json

• A theme should contain a single top-level key called theme, containing the theme's properties

{
    "theme": {
        "name": "myTheme",
        "colors": {
            "primary": "#005DFF",
            ...
        }
        ...
    }
}

modules/Accordion/configuration.js

Learn more about Module Configuration

• The Accordion module will have a name of accordion (lowercase) in the config in order to render the Accordion as lowercase in the DOM (the named used to reference the module internally can be different from the name used when rendering the module to the DOM, which is the purpose of the name property in a module's configuration)
• If a theme exists it can be supplied as an argument to the configuration function and utilised in the configuration

export default theme => ({
    'name': 'accordion',
    'color': 'blue',

    panel: {
        'color': theme.colors.primary
    }
    ...
})

Overriding Modules

You can override a module's default configuration by creating a modules object within the theme object.

• Pass the name of your module (the name used in the module's interface) as a property of the modules object

{
    "theme": {
        "name": "myTheme",
        "colors": {
            "primary": "#005DFF",
        },
        "modules": {
            // Theme-level Accordion properties
            "Accordion": {
                "color": "red"
                ...
            }
        },
        ...
    }
}

...the values used above will override the values in the original modules/Accordion/configuration.js file.

Using a Theme

Several things need to occur for a theme to work, which can be handled with the Synergy.theme() method.

Attach Theme To window.ui

• This exposes it to modules

import theme from './themes/myTheme.json';

window.ui = theme;

Merge Default Config with Theme Config

import Accordion from './modules/Accordion/Accordion.jsx';
import theme from './themes/myTheme.json';

window.ui = theme;

const AccordionConfig = Module.config(Accordion.defaults(window.ui), theme.modules.Accordion);

Assign Updated Accordion Object to Window

• Module.config() is used for merging a module's default configuration with custom configuration

import Accordion from './modules/Accordion/Accordion.jsx';
import theme from './themes/myTheme.json';

window.ui = theme;

const AccordionConfig = Module.config(Accordion.defaults(window.ui), theme.modules.Accordion);

window.Accordion = Object.assign(Accordion, {
    config: AccordionConfig
});

Synergy.theme()

The above tasks can be acted upon all of your modules at once by using the Synergy.theme() method.

• It's recommended to export all of your modules in a single file so they can be imported all at once

import modules from './modules';
import theme from './themes/myTheme.json';

Synergy.theme(modules, theme);

ui Parameter

Synergy.theme() accepts a third parameter to act as a global UI object

Synergy.theme(modules, theme, );