Skip to content

Give each competition its own colours

One theme can serve many competitions, each with its own colours. A competition has no colour fields. Use a theme variable for each colour instead:

  • The theme declares the variable and its default value.
  • Each competition theme profile sets its own value for the variable.
  • A Rive expression reads the value as $t.<name>.

This guide makes one colour variable, sets it for two competitions, and binds it to a Rive colour property. It needs a key with themes:write and competitions:write, a theme with a Rive graphic, and the competitions. To send competitionThemeSettingId to POST /v1/overlays in step 5, the key also needs overlays:write. The theme must support the sport of each competition.

  1. Define a colour variable on the theme.

    Terminal
    curl -X POST 'https://api.ligr.live/rest/v2/themes/203/variables' \
    -H "Authorization: Bearer $LIGR_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{"name":"competitionColour","type":"string","defaultValue":"#1d3557","isStyle":true}'

    A colour is a string variable. Set isStyle so the dashboard groups it with the other style variables. The id of the variable is its name, so later steps use competitionColour as the variableId.

    Write the colour as #rgb, #rrggbb or #rrggbbaa. The alpha comes last. A Rive colour property ignores any other text, for example red, and keeps its current colour.

    Use only letters, digits and _ in the name. An expression can then read it as $t.competitionColour. For a name with other characters, an expression must use $t['my colour'].

  2. Bind the variable to a Rive colour property.

    Terminal
    curl -X PATCH "https://api.ligr.live/rest/v2/themes/203/rive-graphics/$GRAPHIC_ID/data-bindings/Main.accentColor" \
    -H "Authorization: Bearer $LIGR_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{"expression":"$t.competitionColour"}'

    Main.accentColor is the binding id of a colour property in the graphic view model. Read the binding ids with GET /v2/themes/203/rive-graphics/$GRAPHIC_ID. For the other binding operations, see Edit through REST.

    The API does not check $t names. If the name is wrong, the property keeps its Rive colour. An expression can also choose a colour, for example $d.isActive ? $t.competitionColour : '#ffffff'.

  3. Publish the graphic, then publish and activate a theme version.

    Terminal
    curl -X POST "https://api.ligr.live/rest/v2/themes/203/rive-graphics/$GRAPHIC_ID/versions" \
    -H "Authorization: Bearer $LIGR_API_KEY"
    curl -X POST 'https://api.ligr.live/rest/v2/themes/203/versions' \
    -H "Authorization: Bearer $LIGR_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{"activate":true}'

    A theme version freezes the theme variables and the graphic versions. The next step checks each value against the variables of the active version. A variable that is only in the working theme answers 400 Unknown theme variable. For control over which graphic versions the theme version pins, see Publish a theme version.

  4. Create a theme profile for each competition.

    Terminal
    curl -X POST 'https://api.ligr.live/rest/v2/competitions/512/theme-profiles' \
    -H "Authorization: Bearer $LIGR_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "themeId": 203,
    "name": "League colours",
    "themeVariableValues": [{ "variableId": "competitionColour", "value": "#c8102e" }]
    }'
    201 Created
    {
    "id": 88,
    "competitionId": 512,
    "themeId": 203,
    "name": "League colours",
    "defaultControlRoomId": null,
    "isDefault": true,
    "themeVariableValues": [{ "variableId": "competitionColour", "value": "#c8102e" }]
    }

    Send the same request for competition 513 with its own colour, for example #00843d.

    The value must be a JSON string, because the variable type is string. A value of null uses the theme default. A variable that the profile does not list also uses the theme default. The profile name must have 6 to 39 characters.

  5. Show the graphic on an overlay.

    The first profile of a competition becomes its default profile. An overlay for a match of that competition uses the default profile. To use another profile, send its id as competitionThemeSettingId to POST /v1/overlays. See Set up through REST.

    The graphic shows #c8102e for a match of competition 512 and #00843d for a match of competition 513. A competition without a value shows the theme default, #1d3557.

For each theme variable, the graphic uses the first value that is set:

  1. A per-graphic override in the overlay’s theme profile.
  2. The value in the overlay’s theme profile.
  3. The default value of the theme variable.

A null value counts as not set.

Send the new value to the profile.

Terminal
curl -X PATCH 'https://api.ligr.live/rest/v2/competitions/512/theme-profiles/88' \
-H "Authorization: Bearer $LIGR_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"themeVariableValues":[{ "variableId": "competitionColour", "value": "#7a0019" }]}'

themeVariableValues replaces the stored list. Send every value that the profile keeps. A variable that the list leaves out uses the theme default. A field that the request leaves out keeps its value. The dashboard edits the same values: open the competition, select the Theme Profiles tab, and edit the profile’s theme variables.

Profile values are not part of a theme version. A change applies without a new publish. LIGR does not push the change to an open overlay. Reload the overlay page to show the new value.

To change the default colour, send PATCH /v2/themes/203/variables/competitionColour with a new defaultValue. Then publish and activate a new theme version. See Theme variables.