Shared Constants

The Shared Constants Plugin enables users to define and override commonly used static values. It can be leveraged by other plugins to enable localization.

Usage

Core

Create the plugin and add it to Player:

import { Player } from "@player-ui/player";
import { ConstantsPlugin } from "@player-ui/shared-constants-plugin";

const constantsPlugin = new ConstantsPlugin({
  data: {
    prop1: "A",
    prop2: "B",
  },
  namespace: "constants",
  dataPath: "data.props",
});

const player = new Player({
  plugins: [constantsPlugin],
});

You can then query the plugin to get the value of a particular key:

constantsPlugin.getConstants("prop1"); // 'A'

Overriding Values in Content

By default, data can be provided in the constants path of the data object to override the constants that the plugin was initialized with. This can be overridden though via the dataPath configuration option. In the above example, dataPath was initialized with the path data.props therefore the following code snippet could be used to override the prop1 constant:

{
  "data": {
    "props": {
      "prop1": "B"
    }
  }
}

using a similar query for prop1, the value in the content takes precidence and would return B.

If no dataPath is defined, then it defaults to constants and you can still do this

{
  "data": {
    "constants": {
      "prop1": "B"
    }
  }
}

Fallback Values

Any query can also specify an optional default value to return:

constantsPlugin.getConstants("prop3", "default value"); // 'default value'

Examples

Common Types Plugin

The Common Types Plugin leverages this pattern to allow for global contextual message overrides. In order to override those messages you may use something like:

import { Player } from "@player-ui/player";
import { ConstantsPlugin } from "@player-ui/constants-plugion";
import { CommonTypesPlugin } from "@player-ui/common-types-plugin";

const player = new Player({
  plugins: [
    new CommonTypesPlugin(),
    new ConstantsPlugin({
      namespace: "constants",
      dataPath: "data.constants",
      data: {
        validation: {
          lengthError: {
            minimum: "Way too short",
            maximum: "Way too long",
          },
        },
      },
    }),
  ],
});

Any triggerd validation for the length validation will now use the custom error messages. See the Common Types Plugin for more information on the supported overrides and paths.