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 MXML component to the TabbedDocumentFormDispatcher inside the initialization of a Studio plugin, like so:

<editor:TabbedDocumentFormDispatcher>
  <editor:plugins>
    <editor:AddTabbedDocumentFormsPlugin>
      <editor:documentTabPanels>
        <bpforms:CMArticleForm itemId="CMArticle"/>
        ....
      </editor:documentTabPanels>
    </editor:AddTabbedDocumentFormsPlugin>
  </editor:plugins>
</editor:TabbedDocumentFormDispatcher>

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 (an MXML component) in studio/blueprint-forms/src/main/joo/com/coremedia/blueprint/studio/forms/. Containers used in the forms are defined in separate MXML files in the /containers sub directory. The following code shows a simple example for a standard CMArticle form definition:

<?xml version="1.0" encoding="UTF-8"?>
<editor:DocumentTabPanel
        xmlns:fx="http://ns.adobe.com/mxml/2009"
        xmlns:exml="http://www.jangaroo.net/exml/0.8"
        xmlns="exml:ext.config"
        xmlns:editor="exml:com.coremedia.cms.editor.sdk.config"
        xmlns:bpforms="exml:com.coremedia.blueprint.studio.config">
 <fx:Metadata>
    [ResourceBundle('com.coremedia.blueprint.studio.BlueprintTabs')]
  </fx:Metadata>
 <fx:Script><![CDATA[
  public static const xtype:String = "com.coremedia.blueprint.studio.config.cmArticleForm";

  private var config:CMArticleForm;

  public native function CMArticleForm(config:CMArticleForm = null);
  ]]></fx:Script>

  <editor:items>
   <editor:DocumentForm
     title="{resourceManager.getString(
       'com.coremedia.blueprint.studio.BlueprintTabs',
       'Tab_content_title')}">
     <editor:items>
       <editor:PropertyFieldGroup title="My Field Group"
                                  itemId="myFieldGroup">
         <editor:items>
          <editor:StringPropertyField propertyName="title"/>
          <editor:RichTextPropertyField propertyName="detailText"
                                        initialHeight="200"/>
         </editor:items>
       </editor:PropertyFieldGroup>
     </editor:items>
   </editor:DocumentForm>
   <bpforms:CMArticleMetaDataTab bindTo="{config.bindTo}"/>
   <bpforms:MultiLanguageDocumentForm bindTo="{config.bindTo}"/>
   <bpforms:CMArticleSystemForm bindTo="{config.bindTo}"/>
  </editor:items>

</editor:DocumentTabPanel>

Collapsible Property Field Groups

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

Figure 7.2. 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.

<editor:PropertyFieldGroup
  title="{CustomLabels_properties.INSTANCE.PropertyGroup_Details_label}"
  itemId="detailsDocumentForm">
  <editor:items>
    <editor:StringPropertyField propertyName="title"/>
    <editor:RichTextPropertyField propertyName="detailText"
                                  initialHeight="200"/>
  </editor:items>
</editor:PropertyFieldGroup>

Each declaration of an <editor: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 7.1, “Property Fields” for a list of all provided field types.

Each property field of this tab 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 7.4, “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 <editor:<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 com.coremedia.ui.store.DataField. The following example shows how a new column uses a custom field to display the locale property of linked documents.

<editor:LinkListPropertyField propertyName="variants">
  <editor:fields>
    <ui:DataField name="locale"
                  mapping="properties.locale"
                  ifUnreadable=""/>
  </editor:fields>
  <editor:columns>
    <editor:TypeIconColumn/>
    <editor:NameColumn/>
    <editor:StatusColumn/>
    <Gridcolumn id="locale"
                width="30"
                dataIndex="locale"/>
  </editor:columns>
</editor:LinkListPropertyField>

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:

<editor:LinkListPropertyField
        linkType="{'CMTeasable'}"
        linkListSuggesterTemplate="{CustomUtil.getMyTpl()}">
  <editor:linkSuggester>
    <custom:MyCustomLinkSuggester/>
  </editor:linkSuggester>
  <editor:linkSuggesterTemplateExtraFields>
    <ui:DataField name="customField"
                  mapping=""
                  convert="{CustomUtil.getCustomField}"
                  encode="false"/>
    ...
  </editor:linkSuggesterTemplateExtraFields>
</editor:LinkListPropertyField>