Create Custom Themes

Contents:

Overview

To customize the look of KPI Dashboards and Analytical Designer, you can define a theme for your workspace. 

Themes are JSON structures with CSS properties. You can use these properties to customize the visual elements, such as buttons, headings, dashboard content, and navigation.

To customize your workspace appearance:

  1. Create a theme.
    See Define themes.
  2. Upload the theme to your workspace.
    See Upload custom themes.
  3. Activate the theme.
    See Activate custom themes.

Define themes

Themes use special JSON structures with CSS properties. Based on your requirements, define the properties that you want to update.

You can update any number of the properties (only one, or a subset, or all of them). The properties that you do not define in the JSON structure remain intact. See the complete structure below in the complete JSON theme structure.

When creating your themes, follow these rules:

Fonts

Specify both variants of the font (regular and bold). Both variants must be from the same font family.

Use the following formats to external fonts:

  • Absolute URL - "font": "url(https://somewebsite.com/path/to/font.woff)"
  • Explicit format - "font": "url(https://somewebsite.com/path/to/font.woff) format('woff')"

Use the following formats to local fonts:

  • "font": "local(Arial)"
  • "font": "local(Time New Roman)"
  • "font": "local('Times New Roman')"

Example:

"font": "local(font), url(path/to/font.svg) format('svg'),
         url(path/to/font.woff) format('woff'),
         url(path/to/font.otf) format('opentype')"
Colors

Use the following color coding formats:

  • Hexadecimal color without transparency: #ff0 or #ff00ff
  • Hexadecimal color with transparency: #ff06 or #ff00ff80
  • RGB colors: rgb(120,120,120)
  • RGBA colors: rgb(120,120,120,0.6)

Background colors should give enough contrast for texts to be readable.

Borders

Border radius and weight use pixels.

To use a different unit, include it in the string.  Example: "border-radius" : "2em"

Widget borders

The recommended maximum for the widget border radius is 30px.

To hide the border of widgets, use a transparent color instead of borderwidth=0.
Example: "borderColor": "78787800" or "borderColor": "rgb(120,120,120,0)"

Meta section

Regardless of the number of changed properties, every custom theme must include the meta section.

"meta" : {
         "category" : "theme",
         "deprecated" : "0",
         "isProduction" : 1,
         "summary" : "",
         "tags" : "",
         "title" : "{Your theme name}"
      }

Apart from the custom themes, you can also define a custom color palette that to use in charts. For details, see Custom Color Palette in Importing Custom Color Palettes.

Complete JSON theme structure

To customize KPI Dashboards, update the properties in the dashboards section.

To customize Analytical Designer, update the properties in the analyticalDesigner section.

To customize additional common items, update the remaining properties.

This theme includes all properties that you can customize.

{
   "theme" : {
    "content" : {
        "palette" : {
            "primary" : {
               "base" : "#3049D1"
            },
            "error" : {
               "base" : "#e54d42"
            },
            "success" : {
               "base" : "#00c18d"
            },
            "warning" : {
               "base" : "#f4d521"
            }
        },
        "typography" : {
            "font" : "url(https://cdn.jsdelivr.net/npm/roboto-font@0.1.0/fonts/Roboto/roboto-regular-webfont.ttf)",
            "fontBold" : "url(https://cdn.jsdelivr.net/npm/roboto-font@0.1.0/fonts/Roboto/roboto-bold-webfont.ttf)"
        },
        "button" : {
            "borderRadius" : "2",
            "textCapitalization" : true,
            "dropShadow" : true
        },
        "modal" : {
            "title" : {
               "color" : "#6D7680",
               "lineColor" : "#DAE2EA"
            },
            "borderColor" : "#ffffff",
            "borderRadius" : "6",
            "borderWidth" : "2",
            "dropShadow" : true,
            "outsideBackgroundColor" : "#DAE2EA"
        },
        "tooltip" : {
            "color" : "#C8D0FF",
            "backgroundColor" : "#07124E"
        },
        "analyticalDesigner" : {
            "title" : {
               "color" : "#6D7680"
            }
         },
        "dashboards" : {
            "title" : {
               "color" : "#6D7680",
               "backgroundColor" : "#F4F5FB",
               "borderColor" : "#1b4096"
            },
            "navigation" : {
               "title" : {
                  "color" : "#6d7680"
               },
               "borderColor" : "#DAE2EA",
               "item" : {
                  "color" : "#6d7680",
                  "hoverColor" : "#000",
                  "selectedColor" : "#000",
                  "selectedBackgroundColor" : "#F4F5FB"
               },
               "backgroundColor" : "#ffffff"
            },
            "filterBar" : {
               "filterButton" : {
                  "backgroundColor" : "#F4F5FB"
               },
               "backgroundColor" : "#F4F5FB",
               "borderColor" : "#1b4096"
            },
            "section" : {
               "title" : {
                  "color" : "#6D7680",
                  "lineColor" : "#dde4eb"
               },
               "description" : {
                  "color" : "#999EA5"
               }
            },
            "content" : {
               "kpiWidget" : {
                  "title" : {
                     "color" : "#8292E3",
                     "textAlign" : "center"
                  },
                  "kpi" : {
                     "primaryMeasureColor" : "#E8EAF7",
                     "secondaryInfoColor" : "#8292E3"
                  },
                  "borderColor" : "#3049D1",
                  "borderRadius" : "6",
                  "borderWidth" : "1",
                  "backgroundColor" : "#1b4096",
                  "dropShadow" : true
               },
               "widget" : {
                  "title" : {
                     "color" : "#101010",
                     "textAlign" : "center"
                  },
                  "borderColor" : "#ffffff",
                  "borderRadius" : "6",
                  "borderWidth" : "2",
                  "dropShadow" : true
               },
               "backgroundColor" : "#F4F5FB"
            }
         }
    },
      "meta" : {
         "category" : "theme",
         "deprecated" : "0",
         "isProduction" : 1,
         "summary" : "",
         "tags" : "",
         "title" : "Demo theme"
      }
   }
}

Example

You want to change the primary color of the visual elements (blue by default) to green and the font style to Roboto.

The theme definition may look as follows:

{
   "theme" : {
    "content" : {
        "palette" : {
            "primary" : {
               "base" : "#17D901"
            }
        },
        "typography" : {
            "font" : "url(https://cdn.jsdelivr.net/npm/roboto-font@0.1.0/fonts/Roboto/roboto-regular-webfont.ttf)",
            "fontBold" : "url(https://cdn.jsdelivr.net/npm/roboto-font@0.1.0/fonts/Roboto/roboto-bold-webfont.ttf)"
        }
    },
      "meta" : {
         "category" : "theme",
         "deprecated" : "0",
         "isProduction" : 1,
         "summary" : "",
         "tags" : "",
         "title" : "Demo theme I"
      }
   }
}

Upload custom themes

This article assumes that you access your projects at https://secure.gooddata.com/.

  • If you are a GoodData Growth user, replace secure.gooddata.com with the domain from the link that you received in your GoodData confirmation email (for example, yourcompanyname.na.gooddata.com).
  • If you are a white-labeled customer, replace secure.gooddata.com with your white-labeled domain.

You can upload multiple themes, however, only one can be active at a time.

To upload a theme to your workspace, follow  these steps:

  1. Go to https://secure.gooddata.com/gdc/md/{workspace_ID}/obj
    For details about your workspace ID (also called project ID), see Find the Project ID.
  2. Paste your code for the theme in Object definition.
  3. Click submit.
    A confirmation page with a link to your theme is displayed.

If your theme is uploaded, proceed to activating.

Uploading themes with this procedure always creates a new theme. If you want to change an already uploaded theme, see Edit custom themes.

Activate custom themes

Once you submit a theme, it acquires a unique identifier. Use this identifier to activate the theme.

You can locate the identifier in the meta section of the theme code at https://secure.gooddata.com/gdc/md/{workspace_ID}/query/themes

The identifier contains alphanumeric characters. For information about how to change the theme identifier, see Edit custom themes.

To activate your custom theme on the GoodData Portal, you must set the selectedUiTheme platform setting to match the identifier of the theme.

  1. Go to https://secure.gooddata.com/gdc/projects/{workspace_id}/config/.

    If you use LCM, you can simultaneously activate a theme for multiple client workspaces with the same authorization token (so-called "project group") rather than activating it in each client workspace separately. To do so, go to https://https://secure.gooddata.com/gdc/projectGroups/{authorization_token}/config/.

    To find the authorization token, see Find the Project Authorization Token.

    Platform settings configured at the project group level are inherited by the underlying workspaces (including those that may be created using the same authorization token in the future). To configure a platform setting for a project group, you must be a domain admin.

  2. At the bottom of the page in the Key field, type selectedUiTheme.
  3. In the Value field, type the theme identifier.
  4. Click Create config.

Now the theme is configured and your KPI Dashboards use the new settings.

To revert to the default GoodData theme, save the platform setting with an empty Value field.

Edit custom themes

To edit a custom theme, follow these steps:

  1. Go to https://secure.gooddata.com/gdc/md/{workspace_id}/query/themes.
  2. Click on a theme that you want to edit.
  3. Add ?mode=edit to the theme URL in your browser.
    The address may look as follows: https://secure.gooddata.com/gdc/md/daue1szxe5ku2rsztd95sm1tjde4rfpw/obj/76785?mode=edit
  4. Edit the theme.
  5. Click submit.

You can change the theme identifier in the meta section as well.

Manage themes with Life Cycle Management

If you have Life Cycle Management (LCM; see Managing Projects via Life Cycle Management), the custom themes are managed together with all other elements (logical data model, data load processes, dashboards, and so on) within your LCM setup.

This is how it works:

  1. You create custom themes and upload them to the master workspace for a segment.
  2. You run the Rollout brick (see Rollout Brick) that synchronizes all the client workspaces in the synchronized segments with the latest version of the segment's master workspace.

    If you are at the beginning of setting up LCM at your site, this would be done by the Provisioning brick (see Provisioning Brick), which performs the initial synchronization between the master workspace and the client workspaces.

  3. You activate a theme in the client workspaces.

  4. When you need to update the custom themes in the client workspaces, update the themes in the segment's master workspace and run the Rollout brick to propagate the updated themes to the client workspaces.
Powered by Atlassian Confluence and Scroll Viewport.