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 default themes, which you can learn about on the Perspective Built-In Themes page.

In some cases, the default themes may not meet your requirements. For these situations, you can create a custom theme.

Creating a Custom 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 of 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 a custom index.css file.

It's recommended to use one of the bundled themes as an example. Any derivative themes (i.e, light-cool, dark, dark-warm) will serve as ideal examples for most use cases. These themes simply extend the base theme, but override the values of the CSS variables that define fundamental colors. If any of the rules defined in the provided base theme are missing from your custom theme, the result will be reflected in your project. For example, a Button component missing a border. When creating your own custom themes, make sure that rulesets declared in the base theme exist in your custom theme at all times.

When you have ensured that the structure is correct and that an entry file has been defined in the theme resource's config.json, 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. Note that order matters for defined rules. Duplicate rules that come after existing rules will override or supplement depending on declared properties between the rules.

Referencing Base Themes

Base themes light and dark can be copied into the core resources folder by submitting a POST HTTP request {gateway_url}/data/perspective/api/v1/themes/copy-base-themes. This is to make referencing the Inductive Automation base themes easier. The API token used in this request must have write permissions. Any modifications to these copied base themes are ignored.

Structure

In addition to the using Ignition's HTTP OpenAPI, you can create the necessary structure directly in the config file system, in the core resource collection. Any modifications done in the file system will require a rescan, which can be triggered through the API or on the Platform > Systems > Projects Gateway page with the Scan Project System button.

Before getting started, we recommend that you familiarize yourself with the structure of one of our provided themes. A valid theme has the following structure:

```
- custom-theme
|- index.css // theme entry configurable in config.json
|- config.json // theme configuration file
|- resource.json // internal resources file
```

Two important properties are within the config.json, entrypoint and isPrivate. By default, the entrypoint of your theme is index.css. The isPrivate property determines if the theme should be listed as an available theme. By default, this is true. Setting this to false is particularly useful if your theme is shared between multiple themes that are listed as available themes.

Features

CSS Variables

CSS variables have a central role in theme authoring. We recommend leveraging this built-in feature of CSS to aid in modular theme development and ease frustrations of long term maintenance. We use CSS variables throughout our theme stylesheets, so whenever there may be a need to change something like a color, it only needs to be changed in a single file.

Declaring variables

--corporateColor: #FF5D00;

Using variables

background-color: var(--corporateColor);

Descriptive CSS Classes

Component authors can specify unique CSS class selectors that give direct access to styling particular elements. Each class selector is unique enough to prevent clashing, and descriptive enough to minimize any guessing surrounding its dedicated purpose. We follow a standard naming convention called ABEM (Atomic Block Element Modifier).

Syntax Structure

atomicPrefix_blockName__elementName--modifierName

IA Component Example Syntax

ia_cylindricalTankComponent__liquid--animation

Keep in mind that these unique classes give you direct access to specific elements. You can find a list of available selectors, and their defined rules, in their respective files. If you can not find the selector you need, then it is likely not defined. You may either request it or use one of the many other ways to style elements in Perspective.

CSS Imports

Imports provide the ability to develop or author themes in a modular fashion. They also make overriding easy. There are two rules that we expect you to follow when using imports.

• Imports should be declared at the top of each CSS file.

• Each import statement must begin with the CSS at-rule @import, specify the relative path to the file to import, and terminate with a semicolon. Imports that do not meet this criteria may be ignored. You may use single or double quotes surrounding the import path. For example:

   @import "../button.css";  
   @import './variables.css';

Overriding or Adapting Themes

Overriding or adapting themes is done by leveraging the "C" in CSS. Simply add your own CSS import pointing to your own custom style sheet containing the rulesets that you want to override or adapt after any existing imports. For example, to override something declared in the built-in light-cool theme, add your own import in the light-cool/index.css entry file like so:

@import "./light/index.css" 
@import "./custom/overrides.css"

Ignition will only attempt to rewrite this file on startup if it does not exist.

Using a 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.