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:
|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.
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
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.
Widget Type: Checkbox
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
Widget Type: RequirementExternalComments
Widget Type: ExternalLinks
Widget Type: HtmlEditor
Widget Type: Label
This component is used for rendering a read-only text widget.
Widget Type(s): CheckBoxGroup, MultiSelect
Multi-line Text Area
Widget Type: TextArea
Widget Type(s): ComboBox, RadioGroup
Single-line Text widget
Widget Type: Text
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:
Widget Type: Text