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 interface com.coremedia.ui.data.Bean
. Remote beans,
which encapsulate server-side state, conform to the more specific interface
com.coremedia.ui.data.RemoteBean
. Refer to
Section 5.3.2, “Remote Beans” for more details about these concepts.
At first, the more generic Bean
interface 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:
Arrays are equal if they are of the same length and if all elements are equal according to the bean semantics. That is, arrays are treated as values and not as modifiable objects with state.
Date
andCalendar
values are equal if they denote the same date and time, with time zone information taken into account.Blobs as stored in the CMS are equal if they contain the same content with the same content type. As long as the blobs are not fully loaded from the server, a conservative heuristic is used that considers the blobs equal if it is known that they will ultimately represent the same value when loaded.
By using the method updateProperties(newValues)
, you can set multiple
properties at once. The argument object must contain one ActionScript 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 });
Example 5.7. Updating multiple bean properties
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 ActionScript 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
com.coremedia.ui.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 com.coremedia.ui.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:
UNKNOWN
: The bean is still being set up.NON_EXISTENT
: The bean represents an entity that does not exist. Typically, the entity existed at one time in the past, but has been destroyed.UNREADABLE
: The bean represents an entity that exists, but authorization to access it is missing.READABLE
: The bean can be accessed without restrictions.
Local beans are always in state READABLE
.
Singleton Bean
The interface IEditorContext
, whose default instance can be accessed as the
package field com.coremedia.cms.editor.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.