Structs are part of the Unified API and are thus a core product feature.

Implemented by the interfaces Struct and StructBuilder in the Java API, structs provide a way to store dynamically typed, potentially nested objects in the content repository, and thus add the possibility of storing dynamically structured content to the Content Server's static content type system. To this end, the document type schema may define XML properties with the grammar name coremedia-struct-2008. This grammar should use the XML schema http://www.coremedia.com/2008/struct as defined in coremedia-struct-2008.xsd.

In the TypeScript API, structs are modeled as Bean objects. They are directly modifiable. They implement the additional abstract class @coremedia/studio-client.cap-rest-client/struct/Struct to provide access to their dynamic type.

Like every content property value, struct beans are provided as properties of the ContentProperties beans. If a struct bean contains a substruct at some property, that substruct is again represented as a struct bean.

Atomic properties of structs may be accessed just like regular bean properties. Structs can store strings, integers, Boolean, and links to documents as well as lists of these values. All struct properties can be read and written using the ordinary Bean interface. As usual, lists are represented as TypeScript Array objects. Do not modify the array returned for a list-valued property. To modify an array, clone the array, modify the clone, and set the new value at the bean.

In the special case of lists of structs, use the methods addAt() and removeAt() (of the struct containing the struct list) to insert or delete individual entries in the struct list. Note that Struct objects in struct lists represent a substruct at a fixed position of the list. For example, the Struct objects at position 2 will contain the values of the struct previously at position 1 after you insert a new struct at position 0 or 1.

Structs and substructs support property change events. Substructs do not support value change events. You can only listen to a single property of a substruct.

Top-level structs in the TypeScript API are never null. If a content property is bound to an empty XML text, a struct without properties is still accessible on the client. This makes it easier to fill initially empty struct properties.

The most convenient way to access a struct property is by means of a value expression. For example, for navigating from a content property bean to the property bar of the struct stored in the content property foo, you would use the property path foo.bar. You can use these property paths in the standard property fields provided by CoreMedia Studio. This case is shown in the following code fragment:

import Config from "@jangaroo/runtime/Config";
import DocumentTabPanel from "@coremedia/studio-client.main.editor-components/sdk/premular/DocumentTabPanel";
import StringPropertyField from "@coremedia/studio-client.main.editor-components/sdk/premular/fields/StringPropertyField";

//...
Config(DocumentTabPanel, {
  //...
  items: [
    //...
    Config(StringPropertyField, {
      propertyName: "foo.bar",
    }),
  ],
  //...
})

Structs support the dynamic addition of new property values. To this end, the interface Struct provides access to a type object implementing @coremedia/studio-client.cap-rest-client/struct/StructType through the method getType(). You can call the addXXXProperty() methods for various property types during the initialization code that runs after the creation of a document.

import { cast } from "@jangaroo/runtime";

import Content from "@coremedia/studio-client.cap-rest-client/content/Content";
import Struct from "@coremedia/studio-client.cap-rest-client/struct/Struct";

import StudioPlugin from "@coremedia/studio-client.main.editor-components/configuration/StudioPlugin";
import IEditorContext from "@coremedia/studio-client.main.editor-components/sdk/IEditorContext";

class MyStudioPlugin extends StudioPlugin {

  override init(editorContext: IEditorContext): void {
    //...
    editorContext.registerContentInitializer("MyDocumentType",
      MyStudioPlugin.#initStruct);
    //...
  }

  static #initStruct(content: Content): void {
    const properties = content.getProperties();
    let struct = cast(Struct, properties.get("foo"));
    struct.getType().addStringProperty("bar", 200);
  }
}

While it is possible to add a property automatically during the first write, this is not recommended. Some property fields cannot handle an initial value of undefined. You should therefore only bind property fields to initialized properties.