Player Attributes

Player attributes are a mechanism for handling triggering in the playback-flow, as well as containing a data-payload. An attribute is scoped by default to the layout (the layer-set) but can also cross sync-groups, so that multiple players can share state.

An example simple attribute:

interface Attribute {
  name: string;
  active: boolean;
  data?: string;
}

Example:

‘name’ is a combination of type and unique name, separated by a dot - ‘dyn.MyAttribute’

Attribute Types

1. static:

   • Constant settings from a CMS. Even though these can be altered, they should be considered read-only.

2. oneshot:

   • A ‘strobe’ dynamic attribute. When set to active = true, any conditionals in the playback-flow that satisfies the criteria will reset active to false after display. When using this functionality, it’s recommended to always clear active after a short timeout in case the playout-graph does not have any matching conditionals.

3. shared:

   • A dynamic attribute which is shared with all Players in the current layer's sync-group.

4. dynamic (without prefix or prefixed by "dyn" or anything but "static", "oneshot" or "expr"):

   • Any "regular" attribute.

5. expr:

   • Allow one attribute to be dependent on another attribute’s data.
     See the expression attributes guide for more information.

Data

The data-value can contain any string. E.g. JSON.

Setting an Attribute

An Attribute can be set by calling TemplateController.

this.controller.setAttribute({
  name: 'dyn.MyAttribute',
  active: true,
  data: '{ "foo": "baz" }',
});

setAttribute() also has an optional parameter called ‘force’. Normally, the onAttribute() event (see below), will be called only when ‘active’ is toggled. ‘force’ means the state will always be distributed to all active templates.

Getting Attributes

The current set of attributes is included in the Player-metadata supplied to onPreload(). By using the DataHelper, these can be accessed in two ways:

As an attribute-array:

const attr = helper.player.metadata.attributes.find((name) => name === 'dyn.MyAttribute');

As an object-lookup:

const attr = helper.player.attributes['dyn.MyAttribute'];

Attribute Changes

Implement onAttribute() in your View to get called on ‘active’-changes (or always, if the Attribute was updated with ‘force’).

Example of where the class-variable ‘myAttr’ will always have the current value:

class MyView extends Dise.SimpleViewBase {
  myAttr: Dise.Attribute;
  
  async main(helper: Dise.IDataHelper): Promise<void> {
    this.myAttr = helper.player.attributes['dyn.MyAttribute'] ?? {
      name: 'dyn.MyAttribute',
      active: false,
    };
    
        // ...waitForPlay() etc...
  }
  
  onAttribute(attr: Dise.Attribute): void {
    if (attr.name === 'dyn.MyAttribute')
      this.myAttr = attr;
  }
}

Example:

See the Nexmosphere sample project.