Control Descriptor

{
 "Name":"literal1",
 "ControlName":"mx-literal",
 "IsSystem":true,
 "Type":4,
 "Id":"edc6d2b8-8c20-4df8-d9a5-4e493b041a83",
 "Properties":[
    {  "Name":"value", "Value":{ "__type":1, "path":"SPSPrinterType.SPSAssetClassBase.Name" } },
    {  "Name":"name",  "Value":"literal1"}
 ]
}

Transformation

The Control Descriptor has range of configuration settings which influence the was the Control Descriptor instance be transformed to the end-user UI. The main task of this operation is take the well-structured Control object and generate the correct HTML tags, which could be understood by the client browser.
In most of the cases, the default scenarios of transformation ("Auto"), when control name is transformed to HTML Tag, and all related properties is to appropriate HTML attribute, is enough, but there are cases when this approach does not work. For such cases, in the Control Descriptor Advanced View, section "Transformation" defines the properties which impact the transformation process.

Tag Name, defines the HTML Element the Control Descriptor will be transform to. If not set, the System uses Control Descriptor name as target HTML Element.

The System uses the XSLT transformation behind, what means the original Control Descriptor Instance object converted to XML, and then XSL templates is applied.  Two Control Descriptor properties "Body XSLT template" and "Properties XSLT Template", allows to supplement the default transformation mechanism with additional logic. For example, define some control Properties which always need to be added to UI element, or provide a special rendering mechanism for Properties with marked Transformation type "None"

The target structure of the Control Descriptor transformation to the end-user UI element could be represented like:

<tag-name {properties}>{body}</tag-name>

The transformation could be also specified on each property level. Transformation for Property supports three different ways, which regulated by Property Transformation Type: 

• Auto, the property transformed automatically to HTML, uses either Attribute Name (when present) or Name as transformed attribute name. 
• XSLT, on transformation is fully relies on the XSLT Template defined for the Property
• None, property is not rendered to HTML, and Control Descriptor Body or Properties XSLT Temaples could be used to render this Property in a special way

Example: Link Control (present in Control Library)

Link Control is a Control Descriptor for the standard HTML Element <A> (anchor). This control has only two properties Title and Url. And due to <A> element syntactics cannout be automatically transformed because element Title is not an attribute but Element body, e.g. <a href="{Url}">{Title}</a>. To achieve such transformation, we need redefine XSL template for Body rendering.

<xsl:value-of select="properties/property[@name='title']/@value"/>

Control Properties and Property Designers

To configure Control usage for every single case, the  Control Descriptor defines range of Properties, which are publicly available in the Layout Designer Properties View. The list of properties for the Control is automatically generated by aggregating all properties defined in Control Descriptor itself and all of its direct or indirect parents (inherited) Control Descriptor. The picture below shows as the Layout Designer displays properties declared in the Control Descriptor

Property Editors

To simplify the procedure of the Control configuration in Layout Designer, the Solution Builder provides a range of the Property Edotprs. Each available Editor has its own specifics, fit to each concrete purpose of the Property: 

• Property Editor, allows to set static/constant values for the Property value. The System supports the following types of the Property Editor: String (allows specify single line string), Text (multi-line text), Integer (the Editor expects the integer as a value), Localizable (the Layout designer opens the Localization Strings popup, where the Localization String can be selected), Image (allows to pick the known SVG icon as the Propery value), Unit (allows to define values for HTML sizes, e.g. for attribute Width={value}px|rem|%), Complex Data (handles the cases when Property expected not a simple type, but complex data model, like array of Objects, e.g. property Columns for Grid control);
• Bindable Editor, allows to bind the Control Property with Data Model item. The Editor opens the popup which displays all Data Model items matches the Property type. On Picking this Editor in Control Descriptor Property dialog, the System shows the Editor Extensions controls, which allow to specify the Property supported data types;
• Enumeration Editor, builds a in Properties Panel, a drop-down control with items defined in Editor extension control "Enumeration", in the following format: Title:Value
  
• Style Editor,  used by property Style, which present in all Control.  The Editor allows to pick an appearance style of the Control;
• Schema Editor, deals with the picking Schema entities, and allows to set the name of the Configuration Item or Data Definitions to Property value.
• Object Picker Editor, allows to set a static reference to Object present in Production database using the Object Picker control. On picking this Editor type, the System requests also to define the Data Definition from which Object needs to be selected, and also to restrict the Allowed Types,

 

Control Descriptor Inheritance

To simplify the definitions of the Control Descriptor properties, amount of which in some cases could exceeds dozens, and which repeating from control to control (e.g. all control has property Name) the Solution Builder support multi-inheritance mechanism. All the properties of the inherited controls are automatically extend the Control Descriptor, and becomes available for configuration in Layout Designer Properties. In case some of the inherited Property has wrong definition in perspective of the Control Decriptor, or just need to be hidden, this property could be easily redefined on the Control Descriptor, and in case of ambiguity, when there are a few definition of the property with the same name exists, the System picks the property  with lower inheritance index.

Simple Control Descriptor

The implementation of the control relies on a HTML Element which is known in UUX application. Here could be used on of standard HTML element , as well as the self-defined HTML element. The UUX platform is based on AngularJS framework, which has well-defined mechanism of creating and registering "self-defined" HTML elements, which called Directives. The following guide describes how to develop a Directive "Creating Custom Directives".

The good examples of the Simple Control Descriptor based on regular HTML element, as "Link control", which based on standard <A> anchor control. As for the alternative approach, take a look to Text Literal Control Descriptor, which relies on Directive <mx-literal>, which implemented by Matrix42 and delivered in JS library.

Pros: Using this approach has range of benefits:

• Allows implement absolutely any UI element behavior, literally, without limitation;
• Allows to integrate 3-d party components to the Solution Builder.  
• Better performance

Cons:

• The implementing of Directives requires software development skills in area of Javascript and HTML
• The custom JS library need to be deployed, and correctly included to UUX application

For more information how to create and use Simple Control Descriptor, please read article "Add new Control to Layout Designer".

Composite Control Descriptor

It often happens that there is a section of the Layout, which contains a bunch 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 not only very time consuming, but also error-prone, and significantly reduces the maintainability of such solution. Good approach for such case, is using Composite Control Descriptor, which besides the common Control Descriptor properties, has Layout Template behind, and behaves identically to other Layout objects, like Dialog, Preview, etc. Once the Composite Control Descriptor is created the System enables action "Customize" which triggers opening the Layout Designer.

For more details see Composite Control Descriptor page.

General tabulator (Property dialog ) 

Name	The technical name of the Property.
Title	Display Name of the Property, shown in Layout Designer. The value could be localized
Description	Describes the purpose of the Control, displayed as prompt for the property in Layout Designer when users hover over the question mark icon.
Category	Defines the Property Category. The available Categories can be managed in Pickup PDRControlDescriptorPropertyCategoryPickup
Position	Position of the property within the specified Properties Category; the larger the number, the lower the property.
Hidden	Signals the Layout Designer to hide the Property in the Properties pane.
Required	Providing the value for the property is mandatory on configuring Control in Layout Designer. Otherwise the Layout Designer highlights the Property and the Control itself as invalid

Transformation Info tabulator (Property dialog)

Attribute Name: you may specify how the property will appear in html; leave the field empty to use the default value (Name from under the General Info tab); the default value is the most frequently used one. 
Transformation Type: the most frequently used value, Auto, sets the transformation to the Name value. 
Default Value: default value prefilled for the property in Layout Designer. 
Transformation Target: 
XSL Template: you may provide a template for the xsl transformation of the property here; xsl templates are rarely used. 
Render Anyway: select to always add attributes to the control irregardless of their values. 

Designer Info tabulator (Property dialog)

See the chapter Control Properties and Property Designers for more details regarding available Property Editors

Binding Type:

• Two Way binding is used for controls data inside which may change and be transferred elsewhere; Two Way binding supports the Editor.
• One Way option is used for controls data inside which may change but is not transferred anywhere. One Way binding is used, for example, for literals which only display the value and change nothing. The One Way option is better for performance than the Two Way option.