Themes JSON File

Important: In this release, when you enable the Enhanced Experience user interface, users see changes to workflows and the user interface. The classic themes require updates to allow your users to see a consistent color scheme. For more information, see Expand a Theme to Support the Enhanced Experience and Themes and UI Updates. If you're working in an earlier version of this analytics environment, see JSON File Example Updates (Earlier Releases).

JSON File Updates

Work with an existing theme by downloading it, then updating a copy appropriately for your desired color scheme.

Theme Plan Actions Required

You want to design a new color theme, using an existing enhanced-experience theme as a template.

Download the d+a_light theme or other theme that supports the enhanced-experience interface. Edit as needed for your desired colors.
Remove the "system": true and "id": "<string>" properties from the downloaded JSON file before you use it to create your new theme.

Caution: If you don't remove these items, you may overwrite the system themes, and in turn, have your updates overwritten by subsequent software version updates. Composer automatically generates an ID for the theme and sets the value of the "system" property when the API request to create the theme is processed.
Make your changes. Optionally update specific objects in addition to your overall colors design. See Update Specific Items in Your Theme.
Once complete, add to your environment and activate it. See Activate a Theme.

You want to update a standard or custom classic color theme, using an existing classic theme as a template.

Download your custom classic theme or standard classic theme.
Add the sample code provided in JSON Updates to Support Enhanced Experience UI.
Edit as needed for your desired colors. Update the content.customProperties.homePage and content.customProperties.navbar.sidebar sections.
Optionally update specific objects in addition to your overall colors design. See Update Specific Items in Your Theme.
Remove the "system": true and update the "id": "<theme-id>" and "name": "<theme-name>" properties to match the downloaded JSON file.
Make your changes, and follow the instructions to PATCH these updates to the theme you want to use in your environment and activate it. See Patch a Theme.

First, find the id of your theme, then download that theme from your environment. Use it as a template as described in the table above to make appropriate changes to deploy your color selections.

To find your currently active theme id, use the /api/customization/themes/active API endpoint with a GET call.

Note: You can only tailor theme colors. Other tailoring properties (such as fonts or font sizes) should not be changed.

Expand a Theme to Support the Enhanced Experience

If you're upgrading from a previous environment to v26.2 or later, you can activate the d+a_light theme, or edit the d+a_light theme to suit your needs and use the enhanced experience UI.

Alternatively, you can take your existing classic theme and PATCH it by updating appropriate values for your existing theme using the sample below and adding it to your environment using a PATCH command to the themes API endpoint.

These updates are needed to support the new interface features that are a part of enabling the enhanced experience. See Themes and UI Updates.

Caution: Update your custom theme and enable the enhanced-experience toggle before upgrading past version 26.2. The enhanced homepage and navigation will become the standard experience for all users in the near future. We recommend making these updates now to ensure a smooth transition.

JSON Updates to Support Enhanced Experience UI

Update this sample with your appropriate id, name, and other updates, then PATCH to your staging environment to test before deployment to production. See Themes and UI Updates.

{
  "id": "<theme-id>",
  "name": "<theme-name>",
  "content": {
    "customProperties": {
      "homePage": {
        "banner": {
          "background": "$colors.surface",
          "color": "$colors.onSurface",
          "mixBlendMode": "lighten"
        },
        "color": "$colors.onSurface",
        "menuCard": {
          "background": "$colors.surface",
          "color": "$colors.onSurface"
        },
        "title": "$colors.onSurface"
      },
      "navbar": {
        "sidebar": {
          "background": "$colors.primaryVariant",
          "iconColor": "$symphony.colors.white",
          "tabBg": "transparent",
          "tabBgActive": "$symphony.colors.slate.700",
          "tabBgHover": "$symphony.colors.slate.700"
         }
       }
     }
  }
}

Update Specific Items in Your Theme

To change colors used for a specific visual style or a table, use the following substitutions.

Substitution	Description
`<visual-type>`	Specify one of the following: `UBER_BARS`, `SCATTERPLOT`, `PIE`, `MULTI_METRIC_BARS`, `LINE_AND_BARS`, `HISTOGRAM`, `HEAT_MAP`, `FLOATING_BUBBLES`, `DONUT`, `BOX_PLOT`, or `LINE_CHART`.
`<table-type>`	Specify one of the following: `RAW_DATA_TABLE` or `PIVOT_TABLE`.
`<charts-color-parameter>`	Specify one of the base color parameters from the `"charts"` section of the JSON file to change for the selected `<visual-type>`. For example, `"axisLabelColor"`.
`<tables-color-parameter>`	Specify one of the base color parameters from the `"tables"` section of the JSON file to change for the selected `<table-type>`. For example, `"background"`.
`<newsetting>`	Specify the new color setting for the `<charts-color-parameter>` or the `<tables-color-parameter>`.
`<your-palette>`	Specify a name for your color palette, if you choose to add your own, personalized, palette to the environment. Palette names can be referenced in the `palette` property in the `customProperties` section of the JSON under `charts`. They can also be referenced in the `palette` property for individual visual styles (`<visual-type>` sections) under `charts`.
`<hexcolorn>`	Specify the hexadecimal representation of up to 9 colors (where `n` ranges from 1 to 9) for your personalized color palette.
`<color-palette-name>`	Specify the name of a supplied color palette or a color palette defined in this JSON file.

You can specify color settings for more than one visual style or table type. You can also specify more than one color setting for each style or type.

You can specify color settings for more than one visual style or table type. You can also specify more than one color setting for each style or type. For more information on themes, see Manage User Interface Themes.

JSON File Example Updates (Earlier Releases)

To create your own theme, first find the id of your theme, then download that theme from your environment. Use it as a template to make appropriate changes to deploy your color selections.

To find your currently active theme id, use the /api/customization/themes/active API endpoint with a GET call.

Note: You can only tailor theme colors. Other tailoring properties (such as fonts or font sizes) should not be changed.

Be sure to remove the "system": true and "id": "<string>" properties from the JSON file before you use it to create a theme. Composer automatically generates an ID for the theme and sets the value of the "system" property when the API request to create the theme is processed.

You can specify a master theme in the theme JSON using the masterThemeID property. Master themes are optional, but allow you to identify the Composer-supplied theme from which properties should be inherited by a custom theme, if the properties are not specified in the custom theme JSON. Master themes can only be Composer- supplied themes. See Supplied Themes.

Finally, if you are changing the colors used for a specific visual style or a table, use the following substitutions.

Substitution	Description
`<visual-type>`	Specify one of the following: `UBER_BARS`, `SCATTERPLOT`, `PIE`, `MULTI_METRIC_BARS`, `LINE_AND_BARS`, `HISTOGRAM`, `HEAT_MAP`, `FLOATING_BUBBLES`, `DONUT`, `BOX_PLOT`, or `LINE_CHART`.
`<table-type>`	Specify one of the following: `RAW_DATA_TABLE` or `PIVOT_TABLE`.
`<charts-color-parameter>`	Specify one of the base color parameters from the `"charts"` section of the JSON file to change for the selected `<visual-type>`. For example, `"axisLabelColor"`.
`<tables-color-parameter>`	Specify one of the base color parameters from the `"tables"` section of the JSON file to change for the selected `<table-type>`. For example, `"background"`.
`<newsetting>`	Specify the new color setting for the `<charts-color-parameter>` or the `<tables-color-parameter>`.
`<your-palette>`	Specify a name for your color palette, if you choose to add your own, personalized, palette to the environment. Palette names can be referenced in the `palette` property in the `customProperties` section of the JSON under `charts`. They can also be referenced in the `palette` property for individual visual styles (`<visual-type>` sections) under `charts`.
`<hexcolorn>`	Specify the hexadecimal representation of up to 9 colors (where `n` ranges from 1 to 9) for your personalized color palette.
`<color-palette-name>`	Specify the name of a supplied color palette or a color palette defined in this JSON file.

CMP-ZenDesk-v26.4.log-456766021.zip
40 KB Download