Skip to main content
Matrix42 Self-Service Help Center

Composite Control Descriptor

  1. Last updated
  2. Save as PDF

Overview

It often happens that there is a section of the Layout, which contains a set of Controls, and a logic which handles these controls, need to be reused in several Layouts. Repeating the same actions, like constructing a model, arranging controls and their dependencies for each Layout is not only very time consuming, but also error-prone, and significantly reduces the maintainability of such solution.

A good approach for such a case is using Composite Control Descriptor, which besides the common Control Descriptor properties, has a  Layout Template behind, and behaves identically to other Layout objects, like  Dialog ,  Preview , etc. Once the Composite Control Descriptor is created, the System enables Customize action which triggers opening the Layout Designer. 

Control Descriptor Types

There are 2 types of Control Descriptors:

  • Simple Control Descriptors 
  • Composite Control Descriptors

Control Descriptors page includes both of them (see Administration application → User Interface → Control Descriptors). 

Custom Template property denotes the type of the control descriptor. All control descriptors that are marked as Custom Templates are Composite Control Descriptors:

Control_descriptor_custom_template.png

This property is set in the Advanced tab of the Control Descriptor settings.

The main difference between these 2 types:

  • Simple Control Descriptors are created by defining a set of properties in the Control Descriptor dialog, for instance, Literals, Email Descriptor Literals, etc.
  • Composite Control Descriptors are also defined as properties of the Control Descriptor dialog, and besides the basic settings, they are additionally designed in the Layout Designer, in the same way as layout templates.

Thus, unlike Simple Control Descriptors, the Composite Control Descriptors additionally have Customize action that opens a Layout Designer:
Composite_control_customize_action.png

In other words, composite control descriptor is a layout template that includes a set of other control descriptors, both simple or composite, and is combined into a new control descriptor that can be reused on other layout templates that are edited with the Layout Designer. 

Creating Composite Control Descriptor

To create a composite control descriptor:

  1. In Administration application -> User Interface -> Control Descriptors -> click Add Control Descriptor
  2. Specify all necessary Properties of the Control Descriptor. This step is common for both simple and composite control descriptors.
  3. In the Advanced tab of the Control Descriptor settings select the checkbox of the Custom Template property to enable control descriptor editing in the Layout Designer.
    Control_descriptor_custom_template_enable.png
  4. Configure Properties for the Composite Control Descriptor.
  5. Configure the Layout of the Composite Control Descriptor.

Properties

Properties are added in the Properties tab of the Control Descriptor and are displayed as configurable fields of the control descriptor in the Layout Designer:

Composite_CD_properties_add.png

A common characteristic for properties configuration of the Composite Control Descriptor is the limitation in the data types that can be bound with the property.

Composite control descriptors can handle simple variables of the following data types:

  • Guids (GuidType)
  • String (StringType)
  • Booleans (BoolType)
  • Dates (DateType)
  • Numbers (IntType, FloatType)

Composite_CD_properties_edit.png

This ensures that each property has a single setting for data and thus the property is saved and passed correctly in the application runtime.

When the data type is not set, the system considers the data type as Object and it cannot be handled correctly, so avoid using it and explicitly set the accepted data types or consider the workaround suggested below. Otherwise, if the attributes of the object are not used in the dialog, their data will not be retrieved to the layout. Thus, if the object is used only in the composite control descriptor layout, but not in the layout, where the composite control descriptor is added as a part of a template, the data will not be shown.

ObjectReference type and MultiObjectReference properties are not supported.

Save the settings and proceed with the Composite Control Descriptor layout.

Layout

Click Customize action and edit the Composite Control Descriptor in the Layout Designer.

Properties that were added to the Composite Control Descriptor, as described above, are suggested in the Layout Designer as Widget Attributes and can be used in the layout template as follows:

Composite_CD_widget_attributes1.png

Configured Composite Control Descriptor can be reused in other layouts.

Composite Control Descriptor usage in the Layouts

Canvas

Composite control descriptor is added to a layout in the same way as any other control descriptor.

Open the Layout Designer -> Toolbox -> Search by the name of the control descriptor -> drag & drop the control descriptor on the canvas:

Composite_control_toolbox2.png

Proceed with editing the Composite Control Descriptor properties.

Properties

A set of configurable and mandatory properties is specific for each particular control.

  1. Configurable properties are defined in the control descriptor Properties section.
  2. Available in the layout designer properties of the composite control descriptor are displayed as follows:

Composite_CD_model_properties.png

 

Composite Control Descriptor Properties mapping in the Layout Designer 

  • Simple variable: when a property is mapped to a specified attribute it is the most convenient and less error-prone approach that allows rendering all elements and data of the Layout Template that uses a Composite Control Descriptor as a part of its Layout Template. 
    If you need to use data of an object, each attribute of the object that you would like to use should be added as a separate property with its data type in the Composite Control Descriptor, as described above.
  • Object: when a property of a control descriptor is mapped to a whole object (like SPSAssetClassBase or any other) and the attributes of this control descriptor properties are used only in the layout template of the composite control descriptor but not in the main dialog then these properties will not be loaded and work correctly.

If you can't avoid using objects in the Properties of the Composite Control Descriptor, you will need to adjust the Data Model of the Layout where such Composite Control Descriptor is used and create an empty calculation field for each attribute of the object you would like to use in the main layout as follows:

  1. Go to the object in the Data Model section of the Layout Designer;
  2. Click on the attribute of the object you would like to use in the layout;
  3. Click Edit;
  4. Click Save;
  5. As a result, an attribute will be marked as Calculated Property.

Composite_CD_calc_field.png

Repeat these actions for each attribute of the object that you will use with this layout template.

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    How-To
  2. Tags
    1. composite control descriptor
    2. custom template
    3. custom widget