Module: alfresco/forms/controls/BaseFormControl

alfresco/forms/controls/BaseFormControl

This should be extended by all form controls in order to provide a consistent look and feel. It wraps a standard widget (which can be provided by JavaScript toolkits other than Dojo) or multiple widgets and creates the name, description and units labels are appropriate. It also provides the capability for form controls to communicate with each other and dynamically update their appearance and behaviour through configured rules (e.g. to allow progressive disclosure, etc through configuration).

Author:
  • Dave Draper
  • Richard Smith
Support:
  • This module is safe to be extended by 3rd-party widgets or services (at least until the next major release).
Copyright:
  • Copyright (C) 2005-2020 Alfresco Software Limited
License:
Source:

Examples

Example configuration for a required TextBox control:

{
    name: "alfresco/forms/controls/TextBox",
    config: {
       fieldId: "DISTANCE",
       label: "Distance",
       description: "Enter the distance travelled",
       unitsLabel: "miles",
       name: "distance",
       value: "0",
       requirementConfig: {
          initialValue: true
       }
    }
}

Example configuration for Select control:

{
    name: "alfresco/forms/controls/Select",
    config: {
       fieldId: "COLOUR",
       label: "Colour",
       description: "Select a colour from the list",
       name: "colour",
       value: "RED",
       optionsConfig: {
          fixed: [
             { label: "Red", value: "RED" },
             { label: "Green", value: "GREEN" },
             { label: "Blue", value: "BLUE" }
          ]
       }
    }
}

Example configuration for a hidden TextBox that can be dynamically revealed:

{
    name: "alfresco/forms/controls/TextBox",
    config: {
       fieldId: "AGE",
       label: "How old are you?",
       description: "Enter the distance travelled",
       placeHolder: "Age...",
       unitsLabel: "years",
       name: "age",
       visibilityConfig: {
          initialValue: false,
          rules: [
             {
                targetId": "SHOW_AGE",
                is: ["true"]
             }
          ]
       }
    }
}

Extends

Mixes In

Members

___addedToDocument :boolean

Indicates whether or not the form control has been added into the main browser document. This should not be configured or used by any extending widgets.
Type:
  • boolean
Since:
  • 1.0.49
Default Value:
  • false
Source:

_convertStringValuesToBooleans :boolean

Indicates whether or not string values should be converted to a boolean value if possible. This is checked during getValue and [setValue]{@link module:alfresco/forms/controls/BaseFormControl#setValue} to handle value conversion in and out of the widget. This attribute should be honoured if overriding those functions.
Type:
  • boolean
Default Value:
  • false
Source:

_disabled :boolean

The default disabled status is always false (this can be overridden by extending controls).
Type:
  • boolean
Source:

_hadFocus :boolean

This is used to log whether or not this form control has had user focus or not. The reason being that in certain circumstances we might not want to show validation errors until the user has at least made an attempt to enter a value before they are shown validation error messages.
Type:
  • boolean
Default Value:
  • false
Source:

_hadUserUpdate :boolean

This is used to log whether or not the form control has been updated by the user, typically this would be set when the user performs an action (such as typing). Unlike _hadFocus it is not set by all form controls.
Type:
  • boolean
Since:
  • 1.0.89
Default Value:
  • false
Source:

_pendingValidationFailureDisplay :boolean

This is used to log that a validation error message should be displayed once the form control has gained and then lost focus (as indicated by the _hadFocus) attribute. It will be set to true if the form control has not yet gained focus but validation has occurred and revealed that there are error conditions in the current form value.
Type:
  • boolean
Default Value:
  • false
Source:

_pubSubOptionsHandle :object

This gets set to the temporary subscription handle that is created whenever options are dynamically requested by publishing on a configured topic. This information needs to be maintained as a widget instance variable in order for the temporary subscription to be removed and prevent potential memory leaks.
Type:
  • object
Default Value:
  • null
Source:

_required :boolean

The default requirement status is always false (this can be overridden by extending controls).
Type:
  • boolean
Default Value:
  • false
Source:

_visible :boolean

The default visibility status is always true (this can be overridden by extending controls).
Type:
  • boolean
Default Value:
  • true
Source:

addedAndRemovedValues :boolean

Indicates whether values should be set as separate properties for the files added and removed (from the initial state) rather than just a single value representing the files selected.
Type:
  • boolean
Since:
  • 1.0.82
Default Value:
  • false
Source:

addedNameSuffix :boolean

The suffix added to the form control name when addedAndRemovedValues is configured to be true. The concatenated value is then used as the property for the files that have been added to the form controls initial value.
Type:
  • boolean
Since:
  • 1.0.82
Default Value:
  • "_added"
Source:

autoSetConfig :array

Defines an array of rules for auto-setting the value of the widget. Each element in the array is configured in the same way as the visibilityConfig, requirementConfig or disablementConfig in that it should declare a "targetId" attribute (that maps to the "fieldId" of another widget in the same form) and either a "is" or "isNot" array of values of that field to evaluate against. In addition it also needs to set "rulePassValue" and "ruleFailValue" attributes that are the values that will be set on successful or unsuccessful evaluation of the rule.
Type:
  • array
Default Value:
  • null
Source:
Examples

Automatically sets the value of the form control when "SOURCE_FIELD" is 3

autoSetConfig: [
  {
    rulePassValue: "Updated",
    ruleFailValue: "",
    rules: [
       {
          targetId: "SOURCE_FIELD",
          is: ["3"]
       }
    ]
  }
]

Automatically set the value of the form control to that of "SOURCE_FIELD"

autoSetConfig: [
  {
    copyRule: {
      targetId: "SOURCE_FIELD"
    }
  }
]

cssRequirements :Array

An array of the CSS files to use with this widget.
Type:
  • Array
Source:

description :string

A description of the field. This will appear in a tooltip by default. The value supplied will be checked against the available scoped NLS resources to attempt to translate message keys into localized values.
Type:
  • string
Source:

disablementConfig :object

Defines the disablement behaviour of the widget. It is possible for the widget to dynamically be disabled or enabled based on the value of one or more other widgets. See processConfig for the structure to use when configuring the rules

Type:
  • object
Default Value:
  • null
Source:

fieldId :string

This used to uniquely identify the form field. If not explicitly defined in the instantiation configuration then a new UUID will be generated for it. It is important to have an id attribute that is NOT used as the widgetId (to allow duplications - which the dijit/registry would otherwise reject) and to have a value that can be used as a reference that will be unaffected by changes (e.g. when configuring a form field dynamically with the application).
Type:
  • string
Source:

firstValueIsDefault :boolean

When set to true, and this is a multi-value control, then the initial value will - if nothing is specifically set - be set to the first value available.
Type:
  • boolean
Since:
  • 1.0.65
Default Value:
  • true
Source:

getPubSubOptionsImmediately :boolean

Whether - when a publishTopic is available in the supplied optionsConfig - to immediately publish to that topic in order to retrieve any default pubSubOptions for this control. If set to false, then it will not do that initial publish.
Type:
  • boolean
Since:
  • 1.0.33
Default Value:
  • true
Source:

hideValidation :boolean

This indicates whether or not the validation elements are hidden (for example the invalid field indicator and any validation messages). This would typically be used for form dialogs where the fields have no label.
Type:
  • boolean
Since:
  • 1.0.84
Default Value:
  • false
Source:

i18nRequirements :Array

An array of the i18n files to use with this widget.
Type:
  • Array
Source:

inlineHelp :string

Inline help for the field. If this is not empty it will cause a help icon to show which, when clicked, will launch a dialog containing the additional help content.
Type:
  • string
Source:

inlineHelpAltText :string

The alt-text label to use for the inline help indicator.
Type:
  • string
Default Value:
  • "inlinehelp.alttext"
Source:

inlineHelpImg :string

The local image to use for the inline help indicator.
Type:
  • string
Default Value:
  • "help.png"
Source:

inlineHelpWidth :number

The width of the inline help dialog.
Type:
  • number
Default Value:
  • 400
Source:

isPromisedWidget :boolean

This should be overridden when the createFormControl function will return a Promise (that is a widget that will be created asynchronously rather than returned immediately. This allows processing of the control to be deferred until it has been loaded. This will typically be needed when it is not possible to pre-load the required JavaScript files into the cache.
Type:
  • boolean
Default Value:
  • false
Source:

label :string

The label identifying the data to provide. The value supplied will be checked against the available scoped NLS resources to attempt to translate message keys into localized values.
Type:
  • string
Source:

name :string

The value to submit as the name for the data captured by this field when the form is submitted.
Type:
  • string
Source:

noPostWhenValueIs :array

Sometimes multiple form controls might be used to represent a single post parameter. For example a set of radio buttons might present a set of options for a parameter where the last radio button progressively reveals a text box for entering a custom value. In that case the radio buttons form control is superceded by the revealed text box. By setting this attribute to an array containing the values that prevent the form control value being included in the form post it is possible to define that behaviour
Type:
  • array
Default Value:
  • null
Source:

noValueUpdateWhenHiddenOrDisabled :boolean

By default all fields will have their value when a parent form has its value set but in certain cases it may be desirable for fields to not have a data update when they are hidden or disabled. This will be the case when multiple fields are being used to represent the same data but through progressive disclosure only one field is displayed at a time. By overriding this variable a field can request not to have it's value updated when it is hidden or disabled.
Type:
  • boolean
Default Value:
  • false
Source:

options :array

The list of static options
Type:
  • array
Default Value:
  • null
Source:

optionsConfig :object

PLEATE NOTE: This configuration will not be applicable to all form controls

The configuration for options that can be selected from. These can either be "fixed" or requested over the publication/subscription model. It is also possible to configure triggers that cause options to be refreshed (this can be useful when changing the value of one field will result in different options being available for another).

Type:
  • object
Default Value:
  • null
Source:
Examples

Basic fixed options

optionsConfig: {
  fixed: [
    { label: "Option One", value: "1" },
    { label: "Option Two", value: "2" },
    { label: "Option Three", value: "3" }
  ]
}

Basic publication for options

optionsConfig: {
  publishTopic: "ALF_GET_FORM_CONTROL_OPTIONS",
  publishPayload: {
    url: url.context + "/proxy/alfresco/api/people",
    itemsAttribute: "people",
    labelAttribute: "userName",
    valueAttribute: "userName"
  },
  publishGlobal: true
}

Update options when "FIELD1" or "FIELD2" change value

optionsConfig: {
  changesTo: [
    { targetId:"FIELD1" },
    { targetId:"FIELD2" }
  ],
  publishTopic: "GET_OPTIONS_TOPIC"
}

Update options when "TOPIC1" is pulished globally or "TOPIC2" is published on the current scope

optionsConfig: {
  updateTopics: [
    { topic:"TOPIC1", global: true },
    { topic:"TOPIC2", global: false }
  ],
  publishTopic: "GET_OPTIONS_TOPIC"
}

Example requesting options with a payload containing all the current form values

optionsConfig: {
   publishTopic: "ALF_GET_FORM_VALUE_DEPENDENT_OPTIONS",
   publishPayload: {
     publishTopic: "GET_OPTIONS_TOPIC"
   },
   publishGlobal: false // NOTE: It is important to set publishGlobal to false for this to work
}

postWhenHiddenOrDisabled :boolean

By default if a field is hidden or disabled then it's value should not be posted. This allows multiple controls representing the same data to be used together with visibility/disablement rules so that only one control's value] is submitted. This variable has no direct effect on this widget but can be used by other widgets such as the form. Intentionally hidden fields should override the default value so that they are always submitted.
Type:
  • boolean
Default Value:
  • true
Source:

pubSubScope :string

A scope for prefixing all publication and subscription topics. This is so that form controls can be used and not interfere incorrectly with each other.
Type:
  • string
Source:

removedNameSuffix :boolean

The suffix added to the form control name when addedAndRemovedValues is configured to be true. The concatenated value is then used as the property for the files that have been removed from the form controls initial value.
Type:
  • boolean
Since:
  • 1.0.82
Default Value:
  • "_removed"
Source:

requirementConfig :object

Defines the requirement behaviour of the widget. It is possible for the widget to dynamically be required to have a value provided based on the value of one or more other widgets. See processConfig for the structure to use when configuring the rules

Type:
  • object
Default Value:
  • null
Source:

showValidationErrorsImmediately :boolean

Indicates whether or not any validation errors will be shown as soon as the form control is displayed
Type:
  • boolean
Default Value:
  • true
Source:

supportsMultiValue :boolean

Indicates that this form control can have a value which is a subset of the available options that can be chosen from.
Type:
  • boolean
Since:
  • 1.0.65
Default Value:
  • false
Source:

templateString :String

The HTML template to use for the widget.
Type:
  • String
Source:

trimValue :boolean

Indicates whether or not values should be trimmed of whitespace (this only applies to values that are strings).
Type:
  • boolean
Since:
  • 1.0.94
Default Value:
  • false
Source:

type :string

The widget to instantiate.
Type:
  • string
Source:

unitsLabel :string

A label for showing units measurements (e.g. "milliseconds", "MB", etc). The value supplied will be checked against the available scoped NLS resources to attempt to translate message keys into localized values.
Type:
  • string
Source:

validateWhenHidden :boolean

This attribute has been added to retain backwards compatibility with regards to validation of invisible fields. Fields that are invisible are not validated by default but it may be necessary to validate hidden fields that are progressively disclosed. The use case for this addition was the implementation of the Cloud Sync capabilities that required a form to be disabled until a path was selected (but the path field was hidden until a network and site were selected).
Type:
  • boolean
Since:
  • 1.0.94
Default Value:
  • false
Source:

validationConfig :object

This will hold all of the configuration for validation. It is initialised in the constructor.
Type:
  • object
Default Value:
  • null
Source:

validationErrorAltText :string

The alt-text label to use for the validation-error indicator.
Type:
  • string
Since:
  • 1.0.47
Default Value:
  • "validation.error.alttext"
Source:

validationErrorImg :string

The local image to use for a validation-error indicator.
Type:
  • string
Since:
  • 1.0.47
Default Value:
  • "error-16.png"
Source:

validationInProgressAltText :string

The alt-text label to use for the validation in progress indicator.
Type:
  • string
Default Value:
  • "validation.inprogress.alttext"
Source:

validationInProgressImg :string

The local image to use for a validation in progress indicator.
Type:
  • string
Default Value:
  • "ajax_anim.gif"
Source:

validationWarningAltText :string

The alt-text label to use for the validation-warning indicator.
Type:
  • string
Since:
  • 1.0.91
Default Value:
  • "validation.warning.alttext"
Source:

validationWarningImg :string

The local image to use for a validation-warning indicator.
Type:
  • string
Since:
  • 1.0.91
Default Value:
  • "warning-16.png"
Source:

value :string

The value to submit as the value of the field when the form is submitted.
Type:
  • string
Source:

valueDelimiter :string

An optional token that can be provided for splitting the supplied value. This should be configured when the value is provided as a string that needs to be converted into an array.
Type:
  • string
Since:
  • 1.0.82
Default Value:
  • null
Source:

valueSubscriptionTopic :string

The topic whose publication should trigger the setting of the control value from payload.value
Type:
  • string
Default Value:
  • null
Source:

visibilityConfig :object

Defines the visibility behaviour of the widget. It is possible for the widget to dynamically be hidden or displayed based on the value of one or more other widgets. See processConfig for the structure to use when configuring the rules

Type:
  • object
Default Value:
  • null
Source:

wrappedWidget :object

This will be set to the form control that the user will actually interact with (e.g. a text box, check box, etc).
Type:
  • object
Default Value:
  • null
Source:

Methods

_onBlur()

This function is called whenever the form control loses focus. When this happens the _hadFocus attribute is set to true and if the _pendingValidationFailureDisplay has been set to true (by the showValidationFailure function) then the showValidationFailure will be called again to actually display the error message.
Source:

_onFocus()

This function is called whenever the form control gains focus. This results in the suppressContainerKeyboardNavigation function being called to ensure that when the form is placed inside a list the [view]{@link module:alfresco/lists/views/AlfListView} does not use the key presses (typically the cursor keys) to navigate the user around items in the list.
Since:
  • 1.0.63
Source:

addFormControlValue(values)

This function is called from a form when it needs to get the values from all the controls that it contains. The current control will only add its value to the supplied object if appropriate.
Parameters:
Name Type Description
values object The object to update with the current value of the control
Source:

addOption(option, index)

Adds a new option to the wrapped widget.
Parameters:
Name Type Description
option object The option to add
index number The index of the option to add
Source:

alfDisabled(status)

Controls the disability status of the field.
Parameters:
Name Type Description
status boolean The boolean status to set the disablity state of the field to.
Source:

alfRequired(status)

Used to toggle the requirement state of the field.
Parameters:
Name Type Description
status boolean The boolean value to change the requirement state to
Source:

alfVisible(status)

Used to toggle visibility of the field.
Parameters:
Name Type Description
status boolean The boolean value to change the visibility state to.
Source:

autoSetValue(passValue, failValue, hasPassedRule)

This function is called whenever an autoset configuration rules array is evaluated. It sets the widget value depending upon whether or not the rule evaluated successfully or not.
Parameters:
Name Type Description
passValue object The value to set if hasPassedRule is true
failValue object The value to set if hasPassedRule is false
hasPassedRule boolean Indicated whether or not evaluation of the rules were successful
Source:

completeWidgetSetup()

Adds the widget into the current DOM fragment and then sets up subscriptions on widget processing complete publications as we want to wait the most recently requested widget processing to complete (which in all likelihood should be the request that caused the creation of this widget. The callback function will set the value of the form control making sure that the widget has been added to the document as we only set the once it's part of the document to ensure that no unsafe value (e.g. an XSS attack) can be executed as part of the initial page rendering.
Support:
  • This function is safe to be overridden by extending or mixing modules (at least until the next major release). The inherited code must be called in the overriding function and if the inherited function returns a value then that value must be returned by the overriding function.
Source:

constructor()

Source:

convertStringValuesToBoolean(value) → {object}

If the supplied argument is a string then this will convert that value into a boolean. Conversion will only take place if the string is either "true" or "false" otherwise the supplied value will be returned. This conversion will only take place if _convertStringValuesToBooleans is set to true (which is not the default value).
Parameters:
Name Type Description
value object
Source:
Returns:
Type
object

createFormControl(config)

This function must be overriden by extending widgets to create and return an actual form control instance.
Parameters:
Name Type Description
config object The configuration to use when instantiating the form control
Support:
  • This function is safe to be overridden by extending or mixing modules (at least until the next major release). The inherited code does not need to be called however the overriding function must perform the designated action and return the appropriate data where appropriate.
Source:

createOptionsChangesTo(optionsConfig, subscription, index)

Creates the subscription to the supplied topic information. All topics are handled by the updateOptions function.
Parameters:
Name Type Description
optionsConfig object The overriding options config object
subscription object The details of the subscription to create
index number The index of the topic
Source:

createOptionsSubscriptions(optionsConfig, subscription, index)

Creates the subscription to the supplied topic information. All topics are handled by the updateOptions function.
Parameters:
Name Type Description
optionsConfig object The overriding options config object
subscription object The details of the subscription to create
index number The index of the topic
Source:

focus()

Delegates focus calls to the wrapped widget.
Source:

formControlValueChange(attributeName, oldValue, value)

This function is called whenever the value of the wrapped form widget changes. It publishes the details of the change so that other form widgets can update their status based on the value.
Parameters:
Name Type Description
attributeName string
oldValue object
value object
Source:

getInitialOptions(config)

Generate the initial set of options in the following precedence:
  1. PubSub Config
  2. Callback function
  3. Fixed options
Parameters:
Name Type Description
config object The options configuration
Since:
  • 1.0.96
Source:

getOptionsFromPublication(optionsConfig, payload)

This is a built-in options callback that attempts to retrieve options from a publication event where it is assumed that the publication payload. An example of using this function can be found in the getFormWidgets function of the [FormRulesConfigCreatorElement module]{@link module:alfresco/forms/creation/FormRulesConfigCreatorElement}
Parameters:
Name Type Description
optionsConfig object The configuration for options handling defined for the current control
payload object The publication payload
Source:

getPubSubOptions(config)

Sets up a new subscription for options changes and then publishes a request to get those options.
Parameters:
Name Type Description
config string The configuration to use for retrieving options via Pub/Sub
Source:

getValue() → {object}

This gets the value currently assigned to the wrapped widget. It assumes the widget has a single "value" attribute that can be retrieved (i.e. it assumes a Dojo widget). Any extending classes that do not use Dojo widgets (or use multiple widgets) should override this implementation to return the correct value.
Support:
  • This function is safe to be overridden by extending or mixing modules (at least until the next major release). The inherited code must be called in the overriding function and if the inherited function returns a value then that value must be returned by the overriding function.
Source:
Returns:
The current value of the field.
Type
object

getWidgetConfig() → {object}

This is a method that is expected to be overridden. We won't even assume that the widget configuration will be standard Dojo configuration because we might be instantiated a custom or 3rd party library widget.
Support:
  • This function is safe to be overridden by extending or mixing modules (at least until the next major release). The inherited code does not need to be called however the overriding function must perform the designated action and return the appropriate data where appropriate.
Source:
Returns:
The configuration for the form control.
Type
object

hideValidationFailure()

By default this simply removes the "validation-error" and "display" classes to the _validationIndicator and _validationMessage DOM nodes respectively. However, the code has been broken out into a separate function to support extending classes that may provide alternative HTML templates or wish to render errors differently.
Source:

onPromisedWidget(promisedWidget)

This function is called when isPromisedWidget is set to true. It is the function that is hitched to the "then" function of the returned promise and is called when the promise is resolved (e.g. when the widget has been created).
Parameters:
Name Type Description
promisedWidget object The widget that was promised.
Source:

onPubSubOptions(payload)

This is hitched to the subscription set up in the getPubSubOptions function and simply unsubscribes the from the topic generated when requesting the options.
Parameters:
Name Type Description
payload object The published information
Source:

onValueChangeEvent(name, oldValue, value)

Handles the change in value for the current form control by publishing the details of the change and calling the validate function to check that the new value is acceptable.
Parameters:
Name Type Description
name string
oldValue string
value string
Source:

onWidgetAddedToDocument(payload)

This function is set as a callback when the widget is not immediately added to the main document. It is used as a safety check to prevent scripts from being injected into the page (setting a value on a node before it is added into the page will cause it to execute when rendered, but setting once it has been included in the initial rendering will not cause any problems.
Parameters:
Name Type Description
payload object This is expected to be an empty object or null.
Source:

placeWidget()

Handles adding the wrapped widget into the DOM model provided by the template. By default this assumes that the widget is a Dojo widget and calls it's "placeWidget" function.
Source:

postCreate()

Source:

postMixInProperties()

Processes the image source for indicating validation is in progress and its alt-text label.
Source:

processAutoSetConfiguration(config, index)

Called for each entry in the autoSetConfig array. The autoSetValue function will be passed each time the rules are evaluated with the evaluation result and the pass and fail evaluation values to set.
Parameters:
Name Type Description
config object The configuration for the current autoset value
index number The index of the configuration in the original array
Source:

processOptionLabel(option, index)

This is a simple function that is used to convert label message keys into the appropriate translated message.
Parameters:
Name Type Description
option object The option configuration
index number The index of the option
Source:

processOptionsConfig(config)

Processes the configuration for defining options and their update behaviour. This configuration is different to the visibility/requirement/disablement rules so needs to be handled separately. The configuration can be defined in the following structure:

"optionsConfig": {
   "changesTo": [{
      "targetId": "someId",
   }],
   "updateTopics": [
      {
         "topic": "someTopic",
         "global": true
      }
   ],
   "itemsAttribute": "options",
   "publishTopic": "ALF_GET_FORM_CONTROL_OPTIONS",
   "publishPayload": {
      "url": AlfConstants.PROXY_URI + "api/groups",
      "itemsAttribute": "data",
      "labelAttribute": "displayName",
      "valueAttribute": "fullName"
   },
   "callback": "functionName",
   "fixed": [
      { "label": "Option1", "value": "Value1"},
      { "label": "Option2", "value": "Value2"}
   ]
 }

The precendence for setting options is as follows:

  • requestTopic
  • callback
  • fixed
e.g. if a "requestTopic" is provided then any "fixed" options will be ignored.

Parameters:
Name Type Description
config object
Source:

processValidationRules() → {boolean}

This function defines the default validation processing. It should be overridden by extending form controls that do not use the default rules. This function rather than the "validate" function should be overridden because this function simply indicates whether or not the control is valid but the "validate" function controls the rendering of error messages and publication of related events. The rules are only processed if the field is visible and enabled because only those fields have their values included in the overall form value (e.g. invisible fields won't be submitted so it doesn't matter if their contents is invalid)
Source:
Returns:
Indicates whether or not the validation rules were passed successfully
Type
boolean

publishValue(deferred)

This function publishes the current value of the widget. It is provided so that enclosing forms can publish all of its controls values to process all rules.
Parameters:
Name Type Argument Description
deferred Deferred <optional>
 A deferred object can optionally be passed. This will only be resolved as widget value initialization completes.
Source:

removeOption(option, index)

Removes an option from the wrapped widet.
Parameters:
Name Type Description
option object The option to remove
index number The index of the option to remove
Source:

setFormControlValue(values)

This is called from addFormControlValue when evaluation of the field configuration and state confirms the value can be set.
Parameters:
Name Type Description
values object The object to update with the current value of the control
Since:
  • 1.0.82
Source:

setOptions()

This is called to set the latest options.
Source:

setOptionsValue(value, options)

Sets the value if there are options to select from
Parameters:
Name Type Description
value object The value to attempt to set from the available options
options array The options to choose from
Source:

setupChangeEvents()

Whenever a widgets value changes we need to publish the details out to the other form controls (that exist in the same scope) so that they can modify their appearance/behaviour as necessary). This function sets up the default events that indicate that a wigets value has changed. This function can be overridden to handle non-Dojo widgets or when multiple widgets represent a single control. If this function is overridden then the overriding function must ensure that the onValueChangeEvent is function is called when the value of the form control created by the createFormControl function changes.
Support:
  • This function is safe to be overridden by extending or mixing modules (at least until the next major release). The inherited code does not need to be called however the overriding function must perform the designated action and return the appropriate data where appropriate.
Source:

setValue(value)

Sets the value of the form control created by the createFormControl function.
Parameters:
Name Type Description
value object The value to set.
Support:
  • This function is safe to be overridden by extending or mixing modules (at least until the next major release). The inherited code must be called in the overriding function and if the inherited function returns a value then that value must be returned by the overriding function.
Source:

showInlineHelp()

This function is attached to the click event of the inline help icon and will display a dialog containing inline help when called.
Source:

showValidationFailure()

By default this simply adds the "validation-error" and "display" classes to the _validationIndicator and _validationMessage DOM nodes respectively. However, the code has been broken out into a separate function to support extending classes that may provide alternative HTML templates or wish to render errors differently.
Source:

showValidationWarning()

By default this simply adds the "validation-warning" and "display" classes to the _validationIndicator and _validationMessage DOM nodes respectively. However, the code has been broken out into a separate function to support extending classes that may provide alternative HTML templates or wish to render errors differently.
Since:
  • 1.0.91
Source:

startup()

This is a life-cycle is provided as an extension point to be overridden to perform additional actions once the form control has been created.
Support:
  • This function is provided as an extension point and is safe to be overridden by extending or mixing modules (at least until the next major release).
Source:

updateFormControlValue(values, initialization)

This function is called from a form when it needs to set the values from all the controls that it contains. The current control will be updated if appropriate.
Parameters:
Name Type Description
values object The object to set the each form control value from
initialization boolean Indicates whether this call is part of the initialization of the containing form
Source:

updateOptions(optionsConfig, payload)

This function is called when an rule triggering options reload occurs (e.g. the value of another relevant field in the form has been changed).
Parameters:
Name Type Description
optionsConfig object The overriding options config object
payload object The publication payload
Source:

validate() → {boolean}

This function validates the current widget value.
Source:
Returns:
A value indicating whether or not validation passed successfully or not.
Type
boolean

validateFormControlValue()

This function is called from a form when it needs to validate the all the controls that it contains.
Source:

valueSubscribe(payload)

This function is hitched when a 'valueSubscriptionTopic' attribute is set on the control. It takes an inbound payload and if it contains a value property it is applied to the control through the setValue function.
Parameters:
Name Type Description
payload object
Source:

<inner> processCallbackOptions(callback, config)

Handle configuration requests that options be generated through a function call... Note that we're not explicitly handling scope here, it's expected that a hitch call will be used if a scope is required. It is also possible to set the callback as a string which will be matched against a function of the current scope.
Parameters:
Name Type Description
callback function The function to call to get the options for the control
config object The full options configuration
Source:

<inner> processFixedOptions(fixed)

Processes fixed options for the form control.
Parameters:
Name Type Description
fixed array The fixe options to apply to the form control.
Source: