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 states.

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.

3. shared:

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

4. dynamic (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.

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 XY240-241’ sample project.