Beans are objects with an arbitrary number of properties. Properties can be updated, generating events for each change. The name "bean" originates from the concept of Java Beans, which are also characterized by their properties and event handling capabilities. Unlike Java beans, the Studio beans do not enforce a strict typing and naming policy, whereby each property must be represented by individual getter and setter functions. Instead, untyped generic methods for getting and setting properties are provided. Specific bean implementations are allowed to add typed accessors, but are not required to do so.

All beans implement the abstract class @coremedia/studio-client.client-core/data/Bean. Remote beans, which encapsulate server-side state, conform to the more specific class @coremedia/studio-client.client-core/data/RemoteBean. Refer to Section 5.3.2, “Remote Beans” for more details about these concepts. At first, the more generic Bean class is described, which is agnostic of a potential backing by a remote store.

Properties

Individual properties of any bean can be retrieved using the get(propertyName) method, which receives the name of the property as an argument. Arbitrary objects and primitive values are allowed as property values. The set of property names is not limited, but it is good practice to document the properties and their semantics for any given bean. If non-string values are used as property names, they will be converted to a string.

Beans may reference other beans. For example, the Content bean contains a property properties that contains a bean with schema-specific properties, whereas the Content bean itself contains the predefined content metadata, such as creation and publication date, which are defined implicitly for all CoreMedia content objects.

By calling set(propertyName, value):boolean, a property value can be updated. The method returns true if (and only if) the bean was actually changed. Generally, the new value is considered to equal the old value if the === operator considers them equal. There are a number of exceptions, though:

By using the method updateProperties(newValues), you can set multiple properties at once. The argument object must contain one TypeScript property per bean property to be set. Bean properties not mentioned in the argument object are left unchanged. Consider the following example:

bean.updateProperties({
    a: 1,
    b: ["a", "b"],
    c: anotherBean
  });

The above code sets the three properties a, b, and c simultaneously, but the property d keeps its previous value if it was set. Apart from convenience, the main difference compared to three calls like bean.set("a", 1) is that events will be sent only after all properties have been updated. This can be useful when you want to update a bean atomically.

Calling toObject() on a bean will return a snapshot of the current bean state in the form of an object that contains one TypeScript property per bean property.

Events

Property event listeners for a single property are registered with addPropertyChangeListener(propertyName, listener) and removed with removePropertyChangeListener(propertyName, listener). The listener argument must be a function that receives a simple argument of type @coremedia/studio-client.client-core/data/PropertyChangeEvent. This event object contains information about the bean, the changed property and the old and the new value.

A listener function registered with addValueChangeListener(listener) receives events for all properties of the respective bean. When multiple properties are updated, the listener receives one call per updated property. Such listeners can be removed by calling removeValueChangeListener(listener).

For beans, events are dispatched synchronously, before the update call returns.

Bean State

Beans, especially remote beans, may enter different states. The possible states are enumerated in the class @coremedia/studio-client.client-core/data/BeanState. The method getState() provides the current state of the bean. State changes are also reported to all listeners. The event object provides the old and the new bean state.

The possible states are:

Local beans are always in state READABLE.

Singleton Bean

The interface IEditorContext, whose default instance can be accessed as the package field @coremedia/studio-client.main.editor-components/sdk/editorContext, provides the method getApplicationContext(), which returns a singleton local bean. This bean is provided as a starting point for navigating to other singletons and for sharing system-wide state. Individual APIs document the properties of the singleton bean that are set by that API. Be careful when adding custom properties and avoid name clashes.