Control Type

The Control Type defines the custom control. A library file can contain one or many Control Types. All Control Types specified here appear in the Palette Drawer defined for the library.

The detailed description of the properties is provided in the table Control Type Properties:

Control Type Properties

Property Type Restrictions / Initial Value Description
Canvas Icon String Must be a valid relative URI that resolves to an image file in the Components special folder. (Required) Provides the special folder relative URI of the icon that is used when rendering the component in the Form Designer canvas. The icon has to be placed within the Components special folder and it can be an image of type .png, .gif, or .bmp. This icon is used only at design-time.

When a library is first created, a set of initial icons is provided in the icons folder. These icons can be used as placeholders for the three icons needed on a Control Type until a more specific set of icons can be provided.
Constructor Class String Must be a valid JavaScript expression that yields a constructor function object when evaluated at runtime. (Required) Refers to the name of the JavaScript constructor that implements the ControlWrapper interface. The JavaScript file that defines this constructor should be specified as an External Resource reference either at the Library level or the Control Type level.
Data Type Classifier Must be a BOM Primitive Type, Enumeration, or Class Defines the type of the value managed by this Control Type. This is a reference to one of the following types:
  • A built-in BOM Primitive Type
  • An Enumeration
  • A Class

    The Data Type determines what can be bound to the value of controls of this Control Type in the Form model. If the BOM Primitive Type of "Object" is specified for the Data Type, then it allows any complex object to be bound to the value of instances of the Control Type.
Event Event Type Reference Can only reference a built-in Event Type, or Event Types specified in this Library file. Specifies which Event Types can be raised by this Control Type. The runtime ControlWrapper can only raise an event of a given type if it has been declared in the Control Type model. The events specified here will be available in the Form Designer to add as triggers on Rules defined in the Form.
Handles Enter Key Boolean   This is set to true if the underlying widget provides a key handler for the Enter key. The form needs to know this in order to prevent a primary button (for example, 'Submit') from being activated by an Enter keystroke when the custom control has the input focus.
Hint String   (Required) Short description of the Control Type, which is used as a hower help on the icon in the palette.
Label String The library designer should ensure that this is unique within the Library. (Required) Label used in the Forms Designer palette.
Multi-valued Boolean   Indicates whether the value managed by this Control Type is multi-valued. If true, then the value for the control can only be bound to multi-valued values. When this is true, it is up to the implementation of the control to manage multiple values. For a multi-valued control with a simple data type, the runtime value will be set as a JavaScript array. When the control is managing multi-valued structured types, the values will be provided in a list.
Name String
  • Unique within library. The qualified name should be unique in the workspace.
  • Name must begin with controls.

    The initial value is set to controls.control1

 (Required) This is the name of the Control Type that is used when adding a reference from a Form model. The form uses the fully qualified control type name, prefixed by the library qualifier, to avoid name collisions.
Palette Icon 16 String
  • Must be a valid relative URI that resolves to an image file in a Components special folder.
  • Must not be the same as Palette Icon 24
  • Can be an image of type .png, .gif, or .bmp
 (Required) The special folder relative URI of the small (16x16 pixels) icon that is used when rendering the component in the Form Designer palette. The icon has to be placed within the Components special folder. This is used only at design-time.
Palette Icon 24 String
  • Must be a valid relative URI that resolves to an image file in a Components special folder.
  • Must not be the same as Palette Icon 16
  • Can be an image of type .png, .gif, or .bmp
 (Required) The special folder relative URI of the large (24x24 pixels) icon that is used when rendering the component in the Form Designer palette when the 'Large Icons' option is active. The icon has to be placed within the Components special folder. This is used only at design-time.
Qualified Name     This is a read-only property which provides the <library-qualifier>.<element-name> details.
Render Mode String
  • Render Modes supported for Control Types are:
    • normal
    • static
    • view-text
    • view-html
    • grid-edit
  • All Control Types must support normal mode.
  • A Control Type can support only one of view-text or view-html.
 Multi-valued enumerated type that defines the render modes supported by the ControlWrapper. The values are:
  • normal: single instance rendering of the control, such as within vertical and horizontal panes.
  • static: Indicates that the control can be rendered within static panes. If supported, then the ControlWrapper must provide the renderStatic() method.
  • view-text: If specified, then the ControlWrapper must provide a getFormattedValue() method that will return a plain text representation of the value managed by this control.
  • view-html: If specified, then the ControlWrapper must provide a getFormattedValue() method that will return an HTML representation (as a string) of the value managed by this control.
  • grid-edit: Indicates that the Control Type provides a rendering specific to edit mode of grid panes. If this mode is not specified, and the Control Type otherwise supports grid panes, then the normal rendering mode will be used in grid panes.

    The value of getFormattedText() is used in grid panes in the view mode. If neither view-text or view-html is specified, then the grid-edit mode will always be used in grid panes, or will fall back to normal if grid-edit is not specified.

    The Focus capability must be defined for the grid-edit mode.
Supported Parent Pane Pane Type Reference Only one of Supported Parent Pane or Unsupported Parent Pane references can be used within a given Control Type. Specifies a list of pane types that are supported as a direct parent by this Control Type. A control of this Control Type can only be added to panes of types on this list. If neither Supported Parent Pane or Unsupported Parent Pane restrictions are specified, then it is legal to add an instance of this Control Type into any type of pane that will accept it as a child.

Some pane types restrict the type of children they support. For example, grid panes don't allow panes as children; tabbed panes only allow panes as children; an embedded form pane is only allowed to refer another form in the workspace.

Note: No Control Types are supported in the Message Pane. You will not be able to place any Control Type in a Message pane even if it is selected as one of the Supported Parent Pane types.
Supported Type Conversion Control Type Reference Only one of Supported Type Conversion or Unsupported Type Conversion references can be used within a given Control Type. Specifies an explicit list of Control Types to which an instance in a form may be refactored. If not specified, an instance of this Control Type may be refactored to any Control Type. For example: a third party date picker may only permit itself to be refactored to one of the built-in date-time control types.
Unsupported Parent Pane Pane Type Reference Only one of supported Parent Pane or unsupported Parent Pane references can be used within a given Control Type. Specifies a list of pane types that this Control Type does not support as a direct parent. If a pane is included in this list, then it is not possible to place a control of this type into an instance of that pane. If neither Supported Parent Pane or Unsupported Parent Pane restrictions are specified, then it is legal to add an instance of this Control Type into any type of pane that will accept it as a child.
Unsupported Type Conversion Control Type Reference Only one of Supported Type Conversion or Unsupported Type Conversion references can be used within a given Control Type. Specifies an explicit list of Control Types to which an instance in a form may not be refactored. If not specified, an instance of this Control Type may be refactored to any Control Type. For example: a third party slider control may forbid itself to be refactored to a tree control in the same component library.