Creating and Using Custom Perspective Themes

Theme Overview

Themes help customize the look of components in your Perspective Sessions, acting as a foundation from which you can customize components even further using Style Classes. Perspective has some default themes already, which you can learn about on the Perspective Built-In Themes page.

By default, themes are stored as cascading style sheets (CSS) included within the Perspective module. In some cases, the default themes may not meet your requirements. For these situations, you can create a custom theme.

Creating a Custom Theme

Like overriding a built-in theme, custom themes are created via the API documented in the Gateway's API Documentation interface (/openapi). These themes will be stored within a folder that contains all the CSS files, as well as metadata files needed for resource collections. Below is a sample API POST request at /data/api/v1/resources/find/com.inductiveautomation.perspective/themes that will create a custom theme with an index.css file as an entrypoint.

[
    {
        "name": "custom",
        "collection": "core",
        "enabled": true,
        "description": "custom descriptions",
        "config": {
            "entrypoint": "index.css"
        }
    }
]

Once the entrypoint is created, you will use the Update Theme Data File endpoint <gateway_address>/data/api/v1/resources/datafile/com.inductiveautomation.perspective/themes/test/index.css to add the custom index.css file.

Now, you can start adding your own changes to your custom theme file. For example, if you wanted to modify the .ia_button--primary background and text color, you would use the Update Theme Data File endpoint again with the button changes updated in the payload.

Using Your Custom Theme

To use your custom theme, select it from the Session Properties in the Designer using the theme property. You can select your custom theme from the dropdown menu. Keep in mind that changes made to the theme property will become active only after a Gateway restart.

Once you select your custom theme and restart your Gateway, your components will change appearance according to your .css file.

There are some cases in which custom themes aren't enough to get your desired look. You can get around this by using Style Classes to fine-tune your components.