Overview

Widgets are used to make up the UI of edit screens for entities, and include combo boxes, text areas, radio buttons and many more UI components.

Widgets are returned from the Widgets API Resource end point or by using the "Widgets" expand when retrieving an entity or project.

All widgets share the following value/options:

Property	Type	Description
WidgetCategory	string	Either "intrinsic" or "custom", for in-built and custom widgets
Name	string	Name of the inbuilt or custom widget
Label	string	The label for the widget
WidgetType	string	A type-descriminator, used for determining how the widget should be rendered
ImplementationType	string	The handler (class) in code which is used to represent this widget, this information can be used to provide additional customisation to a widget based on what information it represents.
HandlerType	string	The key of the handler being used to render this widget, this information can be used to provide additional customisation to a widget based on what information it represents.
ValueType	string	The JSON Schema type of the value for this widget, these should be consistent with the swagger for the API.
ItemId	string	A unique ID assigned to some inbuilt widgets so they can be handled in special ways within the UI - for example "remote links" for a requirement will not be shown if the requirement is being created, or if it has yet to be synchronized with any remote entities, and that remote links widget is identified by it's ItemId.
Required	Boolean	If present, this determines if the widget is required or not. If the value is not present, the default behaviour of not-required is assumed.
ReadOnly	Boolean	If present, this widget is in a read-only state.
TabIndex	integer	Represents the tab-order of fields on screen - normally widgets are returned in-order anyway, but this can be used for explicit tab-order assignment which does not conform to field order.
Hidden	Boolean	If the value is present, determines if the field is current hidden or not - if not present, the field is assumed to be visible.
FormName	string	Generally retained for internal use by Enterprise Tester, if present, this will be the key used for the key/value pair of this widget when submitted back to the server.
Description	string	Description of the field (descriptions can be captured on the custom field configure screen for each custom field). Descriptions are not currently used within the Enterprise Tester UI, but are available for 3rd party tool developers.

In addition each widget may have more options configured specific to that type of field.

Note: intrinsic fields do not currently include their current value in their representation, the value is instead retrieved from the model, using the 'Name' or 'FormName' as the key.

Widgets

Assign User

The assign user field is used to pick an assignee - it makes use of the Users Search API resource to retrieve users for the picker.

Widget Type: AssignUserPicker

{
  "FieldCategory": "intrinsic",
  "Name": "AssignedTo",
  "Label": "Assigned To",
  "WidgetType": "AssignUserPicker",
  "ImplementationType": "EnterpriseTester.Core.CustomFields.IntrinsicFields.AssignededTo",
  "HandlerType": "AssignedTo",
  "ItemId": "assigned-to",
  "Required": false,
  "TabIndex": 106,
  "FormName": "requirement.AssignedTo"
}

Cascading Select

Widget Type: CascadingSelect

The cascading select is a series of 2 or more combo boxes, where selections and the first level determine what child options can be selected in the second combo etc. The number of combo-boxes requires is determined by the "Levels" property (2 in this case for the example below).

Selections are represented as an array, with the first element being the first-level section, second element being the second-level selection and so on, the field must support optional selection of second/third etc. level options.

 {
  "Levels": 2,
  "Value": [
    {
      "Identifier": "10005",
      "Text": "Level A"
    },
    {
      "Identifier": "10007",
      "Text": "Level 1"
    }
  ],
  "Options": [
    {
      "Identifier": "10005",
      "Text": "Level A",
      "Children": [
        {
          "Identifier": "10007",
          "Text": "Level 1",
          "Children": []
        },
        {
          "Identifier": "10010",
          "Text": "Level 2",
          "Children": []
        }
      ]
    },
    {
      "Identifier": "10006",
      "Text": "Level B",
      "Children": [
        {
          "Identifier": "10008",
          "Text": "Level 2",
          "Children": []
        },
        {
          "Identifier": "10009",
          "Text": "Level 1",
          "Children": []
        }
      ]
    }
  ],
  "FieldCategory": "custom",
  "Name": "Cascading",
  "Label": "Cascading`",
  "WidgetType": "CascadingSelect",
  "ImplementationType": "EnterpriseTester.Plugins.DefectTracking.Fields.DefectTrackerCascadingSelectCustomField",
  "HandlerType": "Defect Tracker Cascading Select",
  "ValueType": "IValue[]",
  "Required": false,
  "TabIndex": 117,
  "FormName": "requirement.Cascading",
  "Description": ""
}

CheckBox

Widget Type: Checkbox

{
  "Value": true,
  "FieldCategory": "custom",
  "Name": "CustomCheckBox",
  "Label": "CustomCheckBox",
  "WidgetType": "CheckBox",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.CheckboxFieldType",
  "HandlerType": "Checkbox",
  "ValueType": "Boolean",
  "Required": false,
  "TabIndex": 108,
  "FormName": "requirement.CustomCheckBox",
  "Description": ""
}

Date Picker

The date picker field expects the date to submitted as a string, conforming to the FormatString (.Net Date/Time format string). In addition the .Net date/time format string, we also include a FormatCode which is a PHP and ExtJS compatible parsing/format syntax (see the Ext.Date documentation for more details).

Widget Type: Date

{
  "FormatCode": "j/i/Y",
  "FormatString": "d/mm/yyyy",
  "FieldCategory": "custom",
  "Name": "CustomDate",
  "Label": "CustomDate",
  "WidgetType": "Date",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.DateField",
  "HandlerType": "Date",
  "ValueType": "Date",
  "Required": false,
  "TabIndex": 109,
  "FormName": "requirement.CustomDate",
  "Description": ""
}

External Comments

Widget Type: RequirementExternalComments

{
  "FieldCategory": "intrinsic",
  "Name": "ExternalComments",
  "Label": "External Comments",
  "WidgetType": "RequirementExternalComments",
  "ImplementationType": "EnterpriseTester.Core.CustomFields.IntrinsicFields.RequirementExternalComments",
  "HandlerType": "RequirementExternalComments",
  "ItemId": "requirementcommentsgrid",
  "Required": false,
  "ReadOnly": true,
  "TabIndex": 109
}

External Links

Widget Type: ExternalLinks

{
  "FieldCategory": "intrinsic",
  "Name": "ExternalLinks",
  "Label": "External Links",
  "WidgetType": "ExternalLinks",
  "ImplementationType": "EnterpriseTester.Core.CustomFields.IntrinsicFields.ExternalLinksGrid",
  "HandlerType": "ExternalLinksGrid",
  "ItemId": "externallinksgrid",
  "Required": false,
  "ReadOnly": true,
  "TabIndex": 110
}

Html Editor

Widget Type: HtmlEditor

{
  "Value": "<b><font color=\"#ff0000\">Hello world</font></b>",
  "FieldCategory": "custom",
  "Name": "CustomRichText",
  "Label": "CustomRichText",
  "WidgetType": "HtmlEditor",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.RichTextField",
  "HandlerType": "RichText",
  "ValueType": "String",
  "Required": false,
  "TabIndex": 114,
  "FormName": "requirement.CustomRichText",
  "Description": ""
}

Label

Widget Type: Label

This component is used for rendering a read-only text widget.

{
  "FieldCategory": "intrinsic",
  "Name": "CreatedBy",
  "Label": "Raised By",
  "WidgetType": "Label",
  "ImplementationType": "EnterpriseTester.Core.CustomFields.IntrinsicFields.Label",
  "HandlerType": "Label",
  "ValueType": "String",
  "Required": false,
  "TabIndex": 102,
  "FormName": "incident.CreatedBy",
  "Value": "Joe Blogs (joeb)"
}

Multi Select

Widget Type(s): CheckBoxGroup, MultiSelect

{
  "Values": [
    "911d5b79-cdf2-477e-ae36-2fb4a0afa2b9",
    "cb3459de-f3a2-4ce5-bb54-25cb20778d5d"
  ],
  "Options": [
    {
      "Identifier": "911d5b79-cdf2-477e-ae36-2fb4a0afa2b9",
      "Text": "A"
    },
    {
      "Identifier": "ad0b2fc6-be31-4be8-83b4-c32ff12e50b6",
      "Text": "B"
    },
    {
      "Identifier": "cb3459de-f3a2-4ce5-bb54-25cb20778d5d",
      "Text": "C"
    }
  ],
  "FieldCategory": "custom",
  "Name": "CustomMultiSelect",
  "Label": "CustomMultiSelect",
  "WidgetType": "MultiSelect",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.MultiSelectField",
  "HandlerType": "MultiSelect",
  "ValueType": "String[]",
  "Required": false,
  "TabIndex": 107,
  "FormName": "requirement.CustomMultiSelect",
  "Description": ""
}

Multi-line Text Area

Widget Type: TextArea

{
  "Value": "This is line 1\nThis is line 2",
  "FieldCategory": "custom",
  "Name": "CustomTextArea",
  "Label": "CustomTextArea",
  "WidgetType": "TextArea",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.TextAreaField",
  "HandlerType": "TextArea",
  "ValueType": "String",
  "Required": false,
  "TabIndex": 105,
  "FormName": "requirement.CustomTextArea",
  "Description": ""
}

Single Select

Widget Type(s): ComboBox, RadioGroup

{
  "Value": "9bf6adcd-d3de-4e0f-b794-1fc898cf0fa4",
  "Options": [
    {
      "Identifier": "9bf6adcd-d3de-4e0f-b794-1fc898cf0fa4",
      "Text": "A"
    },
    {
      "Identifier": "536e8f83-6c4a-4bbd-bd1d-e9c81071f190",
      "Text": "B"
    },
    {
      "Identifier": "bcf55fd1-3f85-4f21-b316-afc5bd085e0f",
      "Text": "C"
    }
  ],
  "FieldCategory": "custom",
  "Name": "CustomComboBox",
  "Label": "CustomComboBox",
  "WidgetType": "ComboBox",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.ComboBoxField",
  "HandlerType": "ComboBox",
  "ValueType": "String",
  "Required": false,
  "TabIndex": 106,
  "FormName": "requirement.CustomComboBox",
  "Description": ""
}

Single-line Text widget

Widget Type: Text

{
  "Value": "Hello world",
  "MinLength": 1,
  "MaxLength": 1024,
  "MaxLengthText": "Field must be between 1 and 1024 characters long",
  "MinLengthText": "Field must be between 1 and 1024 characters long",
  "FieldCategory": "custom",
  "Name": "CustomText",
  "Label": "CustomText",
  "WidgetType": "Text",
  "ImplementationType": "EnterpriseTester.Plugins.CustomFields.Handlers.TextField",
  "HandlerType": "Text",
  "ValueType": "String",
  "Required": false,
  "TabIndex": 104,
  "FormName": "requirement.CustomText",
  "Description": "",
  "EmptyText": "Please enter some text"
}

Time Span

Time span fields are rendered using the text widget - to provide an alternative representation of this field in your own tool, use the HandlerType or ImplementationType to detect the presence of the estimated or actual duration fields: