The following section describes how to customize the document forms, which constitute the main working component that your users will use. Studio allows you to organize a - potentially quite big - set of property fields into horizontal tabs.

To register your custom document form, you need to register your TypeScript component to the TabbedDocumentFormDispatcher inside the initialization of a Studio plugin, like so:

import Config from "@jangaroo/runtime/Config";
import TabbedDocumentFormDispatcher from "@coremedia/studio-client.main.editor-components/sdk/premular/TabbedDocumentFormDispatcher";
import AddTabbedDocumentFormsPlugin from "@coremedia/studio-client.main.editor-components/sdk/plugins/AddTabbedDocumentFormsPlugin";
import MyCMArticleForm from "./MyCMArticleForm";

//...
Config(TabbedDocumentFormDispatcher, {
  plugins: [
    Config(AddTabbedDocumentFormsPlugin, {
      documentTabPanels: [
        Config(MyCMArticleForm, { itemId: "CMArticle" }),
        //...
      ],
    }),
  ],
})

The above code plugs into the TabbedDocumentFormDispatcher, and registers custom document forms with the plugin namespace bpforms. Note that the itemId still corresponds to the name of the document type you want to apply your form for.

The document forms registered with the dispatcher are automatically used for both the regular document form and for the left-side form of the version comparison view and the master side-by-side view. When used on the left side, the forceReadOnlyValueExpression passed to the form is set to true, allowing your form to switch into a read-only mode.

To customize a form, you need to adapt the respective form definition file (a TypeScript component) in @coremedia-blueprint/studio-client.main.blueprint-forms (under src/forms). The following code shows a simple example for a standard CMArticle form definition:

import DocumentForm from "@coremedia/studio-client.main.editor-components/sdk/premular/DocumentForm";
import DocumentTabPanel from "@coremedia/studio-client.main.editor-components/sdk/premular/DocumentTabPanel";
import Config from "@jangaroo/runtime/Config";
import ConfigUtils from "@jangaroo/runtime/ConfigUtils";
import BlueprintTabs_properties from "../BlueprintTabs_properties";
import CMArticleSystemForm from "./components/CMArticleSystemForm";
import DefaultExtraDataForm from "./components/DefaultExtraDataForm";
import MultiLanguageDocumentForm from "./containers/MultiLanguageDocumentForm";
import PropertyFieldGroup from "@coremedia/studio-client.main.editor-components/sdk/premular/PropertyFieldGroup";
import StringPropertyField from "@coremedia/studio-client.main.editor-components/sdk/premular/fields/StringPropertyField";
import RichTextPropertyField from "@coremedia/studio-client.main.ckeditor4-components/fields/RichTextPropertyField";

class CMArticleForm extends DocumentTabPanel {
  static override readonly xtype: string = "com.coremedia.blueprint.studio.config.cmArticleForm";

  constructor(config: Config<CMArticleForm>) {
    super(ConfigUtils.apply(Config(CMArticleForm, {
      items: [
        Config(DocumentForm, {
          title: BlueprintTabs_properties.Tab_content_title,
          items: [
            Config(PropertyFieldGroup, {
              title: "My Field Group",
              itemId: "myFieldGroup",
              items: [
                Config(StringPropertyField, {
                  propertyName: "title",
                }),
                Config(RichTextPropertyField, {
                  propertyName: "detailText",
                  initialHeight: "200",
                }),
              ],
            }),
          ],
        }),
        Config(DefaultExtraDataForm),
        Config(MultiLanguageDocumentForm),
        Config(CMArticleSystemForm),
      ],
    }), config));
  }
}

export default CMArticleForm;

Collapsible Property Field Groups

To add several property fields to a group with an additional title, the component PropertyFieldGroup can be used. All documents forms of CoreMedia Blueprint use it to provide a better overview about related fields.

Figure 9.3. Document form with a collapsible property field group

Additionally, the collapsible property field group persists the collapsed status. For example, when the group is collapsed for the teaser title and teaser text of an article, the group is collapsed for all newly opened article documents too (except it contains an invalid field). This status information is stored in the user preferences of the user, so if the user logs into Studio on another computer, the same state will be restored.

import Config from "@jangaroo/runtime/Config";
import PropertyFieldGroup from "@coremedia/studio-client.main.editor-components/sdk/premular/PropertyFieldGroup";
import CustomLabels_properties from "@coremedia-blueprint/studio-client.main.blueprint-forms/CustomLabels_properties";
import StringPropertyField from "@coremedia/studio-client.main.editor-components/sdk/premular/fields/StringPropertyField";
import RichTextPropertyField from "@coremedia/studio-client.main.ckeditor4-components/fields/RichTextPropertyField";

Config(PropertyFieldGroup, {
  title: CustomLabels_properties.PropertyGroup_Details_label,
  itemId: "detailsDocumentForm",
  items: [
    Config(StringPropertyField, {
      propertyName: "title",
    }),
    Config(RichTextPropertyField, {
      propertyName: "detailText",
      initialHeight: "200",
    }),
  ],
})

Each declaration of a PropertyFieldGroup element should contain the attributes title and itemId. The title attribute applies a title to the panel (and also provides a meaning to the group). It is also used as click area for collapsing the panel. The itemId should be applied to persist the state of the group. If no itemId is provided, the collapsible state is not stored in the user preferences and therefore not applied when new documents of the same type are opened.

Property Fields

CoreMedia Studio offers at least one predefined property field for each property type available for CoreMedia documents. See Table 9.1, “Property Fields” for a list of all provided field types.

Each property field of this table has at least an attribute propertyName which corresponds to the property name of the document type. The property name must be specified for each field. The document form also provides three additional properties to all fields without specifying them explicitly: bindTo, hideIssues, and forceReadOnlyValueExpression. The standard property fields recognize these options and custom property fields are encouraged to so, too. See Section 9.6, “Customizing Property Fields” for details about developing new property fields.

Other attributes might vary depending on the property type. The BlobPropertyField editor, for example, has a property contentType that defines the MIME type. If you want to hide a property, you can simply remove the related <PropertyType>PropertyField element. The order of the editor elements defines the order in the form.

Customizing Columns in Link List Properties

By default, the LinkListPropertyField shows a document type icon, the name and the lifecycle status for each linked document. Additionally, the boolean property showThumbnails can be set to true to enable a thumbnail preview for the referenced document. Also, you can configure an array of columns to be shown using the columns property of the field component. Each array element must be an Ext JS grid column object. The available fields of the store backing the grid panel are name, status, type, and typeCls. These fields represent the name, the lifecycle status, the document type name and a style class for a document type icon, respectively.

If you need additional fields for your custom columns, you can add them using the fields property. Each field should be a @coremedia/studio-client.ext.ui-components/store/DataField. The following example shows how a new column uses a custom field to display the locale property of linked documents.

import Config from "@jangaroo/runtime/Config";
import Column from "@jangaroo/ext-ts/grid/column/Column";
import LinkListPropertyField from "@coremedia/studio-client.main.editor-components/sdk/premular/fields/LinkListPropertyField";
import DataField from "@coremedia/studio-client.ext.ui-components/store/DataField";
import NameColumn from "@coremedia/studio-client.ext.cap-base-components/columns/NameColumn";
import StatusColumn from "@coremedia/studio-client.ext.cap-base-components/columns/StatusColumn";
import TypeIconColumn from "@coremedia/studio-client.ext.cap-base-components/columns/TypeIconColumn";

//...
Config(LinkListPropertyField, {
    fields: [
        Config(DataField, {
            name: "locale",
            mapping: "properties.locale",
            ifUnreadable: null,
        }),
    ],
    columns: [
        Config(TypeIconColumn),
        Config(NameColumn),
        Config(StatusColumn),
        Config(Column, {
            header: "Locale",
            width: 270,
            dataIndex: "locale",
        }),
    ],
})

Whereas the configured fields are added to the default fields, the configured columns completely replace the default columns. That is, if you want to keep the predefined fields, you have to repeat their definitions as shown in the example.

Customizing Suggestions and Search Strategy in Link List Properties

The LinkListPropertyField's drop area displays suggestions and search results for new list entries. Suggestions and search results can be adjusted in the LinkListPropertyField by configuring a custom linkSuggester, a corresponding linkSuggesterTemplate and linkSuggesterTemplateExtraFields. The following code example shows how to customize the field:

import Config from "@jangaroo/runtime/Config";
import LinkListPropertyField from "@coremedia/studio-client.main.editor-components/sdk/premular/fields/LinkListPropertyField";
import DataField from "@coremedia/studio-client.ext.ui-components/store/DataField";
import CustomUtil from "./CustomUtil";
import MyCustomLinkSuggester from "./MyCustomLinkSuggester";

//...
Config(LinkListPropertyField, {
    linkType: "CMTeasable",
    linkListSuggesterTemplate: CustomUtil.getMyTpl(),
    linkSuggester: Config(MyCustomLinkSuggester),
    linkSuggesterTemplateExtraFields: [
        Config(DataField, {
            name: "customField",
            mapping: "",
            convert: CustomUtil.getCustomField,
            encode: false,
        }),
    ],
})