Module: alfresco/forms/Form

alfresco/forms/Form

This is the root module for all Aikau forms. It is intended to work with widgets that extend the BaseFormControl and handles setting and getting there values as well as creating and controlling the behaviour of buttons that can be used to publish the overall value of the controls that the form contains.

By default forms will show error messages against any fields that contain invalid data when the form is first displayed. If you'd prefer to give the user a chance to enter or change the data before validation errors are displayed then this can be achieved by configuring the showValidationErrorsImmediately to be false.

It is also possible to setup a form to automatically publish itself whenever its values change, and optionally to also do so if any of its values are invalid. If the autoSavePublishTopic is specified, then the OK and Cancel buttons are automatically hidden.

Configuration can be provided to create rules that display one or more warnings based on the changing values of fields in the forms. The position of the warnings can be configured to either be at "top" or "bottom" of the form.

PLEASE NOTE: If you want to layout your form controls in a specific manner (e.g. in a horizontal line or within tabs) then you should use dedicated form control layout widgets such as ControlRow or TabbedControls as the basic layout widgets do not provide all the required functionality.

Author:
  • Dave Draper
Support:
  • This module is safe to be used in an Aikau page model (at least until the next major release).
Copyright:
  • Copyright (C) 2005-2020 Alfresco Software Limited
License:
Source:

Examples

Example configuration for auto-publishing (including invalid) form:

{
   name: "alfresco/forms/Form",
   config: {
      autoSavePublishTopic: "AUTOSAVE_FORM",
      autoSavePublishGlobal: true,
      autoSaveOnInvalid: true,
      widgets: [
         {
            name: "alfresco/forms/controls/TextBox",
            config: {
               name: "control",
               label: "Autosave form control (even invalid)",
               requirementConfig: {
                  initialValue: true
               }
            }
         }
      ]
   }
}

Example configuration for form that does not show validation errors on initial display:

{
   name: "alfresco/forms/Form",
   config: {
      okButtonPublishTopic: "SAVE_FORM",
      okButtonLabel: "Save",
      showValidationErrorsImmediately: false,
      widgets: [
         {
            name: "alfresco/forms/controls/TextBox",
            config: {
               name: "control",
               label: "Name",
               requirementConfig: {
                  initialValue: true
               }
            }
         }
      ]
   }
}

Example configuration for form with additional buttons:

{
   name: "alfresco/forms/Form",
   config: {
      okButtonPublishTopic: "SAVE_FORM",
      okButtonLabel: "Save",
      showValidationErrorsImmediately: false,
      widgets: [
         {
            name: "alfresco/forms/controls/TextBox",
            config: {
               name: "control",
               label: "Name",
               requirementConfig: {
                  initialValue: true
               }
            }
         }
      ],
      widgetsAdditionalButtons: [
         {
            name: "alfresco/buttons/AlfButton",
            config: {
               label: "Button 1 (includes form values)",
               publishTopic: "CUSTOM_TOPIC_1",
               publishPayload: {
                  additional: "data"
               } 
            }
         },
         {
            name: "alfresco/buttons/AlfButton",
            config: {
               updatePayload: false,
               label: "Button 1 (does not include form values)",
               publishTopic: "CUSTOM_TOPIC_2",
               publishPayload: {
                  only: "data"
               } 
            }
         }
      ]
   }
}

Extends

Mixes In

Members

_form :object

Type:
  • object
Default Value:
  • null
Source:

_formSetupComplete :boolean

This attribute is used to indicate whether or not the form has completed setting up all of the controls it has been configured with.
Type:
  • boolean
Default Value:
  • false
Source:

additionalButtons :object[]

If more than just "OK" and "Cancel" buttons are required then this can be configured to be an array of configurations for extra buttons to be displayed. The payload of these buttons will always be augmented with the form values.
Type:
  • object[]
Default Value:
  • null
Source:

autoSaveOnInvalid :boolean

When autoSavePublishTopic is configured this attribute can be set to true to indicate that publishing should also occur when the form contains invalid values. If this is enabled, then the publish payload will have an additional alfFormInvalid property, which will be set to true.
Type:
  • boolean
Default Value:
  • false
Source:

autoSavePublishGlobal :string

Indicates that the autoSavePublishTopic should be published on the global scope.
Type:
  • string
Default Value:
  • null
Source:

autoSavePublishPayload :object

Additional data to be published on the autoSavePublishTopic along with the form value.
Type:
  • object
Default Value:
  • null
Source:

autoSavePublishTopic :string

If this is not null, then the form will auto-publish on this topic whenever a form's values change. This setting overrides (and removes) the form buttons so that they are no longer displayed. Auto-saving will not occur if the form is in an invalid state unless autoSaveOnInvalid is configured to be true.

PLEASE NOTE: If the form is being dynamically created after page load has completed (e.g. if the form is being displayed in a dialog for example) then in order for auto-saving to occur it will also be necessary to configure the waitForPageWidgets attribute to be false.

Type:
  • string
Default Value:
  • null
Source:

cancelButton :object

A reference to the "Cancel" button for the form. TODO: It should be possible to configure alternative labels for the button.
Type:
  • object
Default Value:
  • null
Source:

cancelButtonLabel :string

The label that will be used for the "Cancel" button. This value can either be an explicit localised value or an properties key that will be used to retrieve a localised value.
Type:
  • string
Default Value:
  • "form.button.cancel.label"
Source:

cancelButtonPublishGlobal :object

Type:
  • object
Default Value:
  • null
Source:

cancelButtonPublishPayload :object

Type:
  • object
Default Value:
  • null
Source:

cancelButtonPublishTopic :string

Type:
  • string
Default Value:
  • null
Source:

convertFormToJsonString :boolean

Type:
  • boolean
Default Value:
  • false
Source:

cssRequirements :object[]

An array of the CSS files to use with this widget.
Type:
  • object[]
Default Value:
  • [{cssFile:"./css/Form.css"}]
Source:

displayButtons :boolean

Indicates whether or not to create buttons for this form.
Type:
  • boolean
Default Value:
  • true
Source:

firstFieldFocusOnLoad :boolean

Should the first field in the form be focused when the form is loaded?

NOTE: If more than one form on a page has this setting, then the order in which the fields are focused cannot be guaranteed.

Type:
  • boolean
Since:
  • 1.0.49
Default Value:
  • false
Source:

formSubmissionTriggerTopic :string

This is an optional topic that can be provided to allow other widgets to trigger the submission of the form. This was added to support requirements of the FormsRuntimeService and in particular the Transitions control.
Type:
  • string
Since:
  • 1.0.86
Default Value:
  • null
Source:

i18nRequirements :object[]

An array of the i18n files to use with this widget.
Type:
  • object[]
Default Value:
  • [{i18nFile: "./i18n/AlfDialog.properties"}]
Source:

invalidFormControls :object[]

This will be instantiated as an array and used to keep track of any controls that report themselves as being in an invalid state. The "OK" button for submitting the form should only be enabled when this list is empty.
Type:
  • object[]
Default Value:
  • null
Source:

okButton :object

A reference to the "OK" button for the form. TODO: It should be possible to configure alternative labels for the button
Type:
  • object
Default Value:
  • null
Source:

okButtonClass :string

Additional CSS clases to apply to the confirmation button on the form. This defaults to have the "call-to-action" style, but this can be overridden as required.
Type:
  • string
Since:
  • 1.0.33
Default Value:
  • "call-to-action"
Source:

okButtonDisableOnPublish :boolean

Whether to disable the OK button after a publish. If this is set to true then the published-label will remain in-place until the button is re-enabled by use of either the okButtonEnablementTopics or [okButtonReenableSecs]{@link module:alfresco/alfresco/forms/Form#okButtonReenableSecs} properties.
Type:
  • boolean
Since:
  • 1.0.44
Default Value:
  • false
Source:

okButtonEnablementTopics :Array.<string>|Array.<object>

If okButtonDisableOnPublish has been set to true and this property is provided then the button will remain disabled until one of these topics has been published (scoped as necessary). The array should contain either strings for unconditional re-enablement if that topic is published or rule objects with an additional topic attribute that defines the topic aname to conditionally subscribe to.
Type:
  • Array.<string> | Array.<object>
Since:
  • 1.0.44
Default Value:
  • null
Source:

okButtonLabel :string

The label that will be used for the "OK" button. This value can either be an explicit localised value or an properties key that will be used to retrieve a localised value.
Type:
  • string
Default Value:
  • "form.button.ok.label"
Source:

okButtonPublishedLabel :string

The label that will be used for the "OK" button after a publish. It will return to the configured label after okButtonPublishRevertSecs seconds (but also see okButtonDisableOnPublish).
Type:
  • string
Since:
  • 1.0.44
Default Value:
  • "form.button.ok.label.published"
Source:

okButtonPublishGlobal :string

Type:
  • string
Default Value:
  • null
Source:

okButtonPublishPayload :object

Type:
  • object
Default Value:
  • null
Source:

okButtonPublishRevertSecs :number

When the OK button has been pushed, the label will changed to the published-label and will also disable if okButtonDisableOnPublish is set to true. Unless the okButtonEnablementTopics property has been provided, both changes will automatically be reverted after this property's value in seconds has passed.

See [this comment from UX]{link https://issues.alfresco.com/jira/browse/AKU-683?focusedCommentId=425326&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-425326} for the reason for this property.

Type:
  • number
Since:
  • 1.0.44
Default Value:
  • 0
Source:

okButtonPublishTopic :string

Type:
  • string
Default Value:
  • null
Source:

postUrl :string

The URL that the form will be posted to
Type:
  • string
Source:

publishValueSubscriptions :string[]

If any of these topics are published then publish this form using the okButtonPublishTopic. One may often wish to use topics.ENTER_KEY_PRESSED as a value in this array, to cause the form to submit when ENTER is pressed.
Type:
  • string[]
Since:
  • 1.0.49
Default Value:
  • null
Source:

scopeFormControls :boolean

Indicates that the a new pubSubScope should be generated for this widget so that it's form controls will be scoped to only communicate with this instance and not "pollute" any other forms that may also be on the page.
Type:
  • boolean
Default Value:
  • true
Source:

setHash :boolean

When this is set to true the URL hash fragment will be updated when the form is published.
Type:
  • boolean
Default Value:
  • false
Source:

setValueTopic :string

This should be set to a specific topic that can be published on to set the value of the form. The default value is null (e.g. setting via publication will not be possible unless a topic is explictly configured). The setValueTopicGlobalScope and setValueTopicParentScope should also be set accordingly.
Type:
  • string
Default Value:
  • null
Source:

setValueTopicGlobalScope :boolean

This indicates whether any setValueTopic subscription should be made globally.
Type:
  • boolean
Default Value:
  • true
Source:

setValueTopicParentScope :boolean

This indicates whether any setValueTopic subscription should be made to the parent scope.
Type:
  • boolean
Default Value:
  • false
Source:

showCancelButton :boolean

Indicates whether or not the "Cancel" button should be displayed or not.
Type:
  • boolean
Default Value:
  • true
Source:

showOkButton :boolean

Indicates whether or not the "OK" button should be displayed or not.
Type:
  • boolean
Default Value:
  • true
Source:

showValidationErrorsImmediately :boolean

Indicates that any validation errors that are present on the fields contained within the form will be shown immediately when the form is displayed. Validation will still occur if this is configured to be false (so it will not be possible to submit an invalid form).
Type:
  • boolean
Default Value:
  • true
Source:

templateString :String

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

useHash :boolean

When this is set to true the current URL hash fragment will be used to initialise the form value and when the form is submitted the hash fragment will be updated with the form value. If you intend to use hashing it is recommended that the okButtonPublishTopic does not directly result in submission of data, but rather submission of data is triggered by changes to the hash.
Type:
  • boolean
Default Value:
  • false
Source:

validFormValuesPublishGlobal :string

Set to true if a the validFormValuesPublishTopic shall be globally published.
Type:
  • string
Default Value:
  • false
Source:

validFormValuesPublishOnInit :boolean

If set to true the form will fire an event when it has been processed (as long as all values are valid)
Type:
  • boolean
Default Value:
  • false
Source:

validFormValuesPublishPayload :object

The payload of validFormValuesPublishTopic. If left as null the form's value will be dispatched.
Type:
  • object
Default Value:
  • null
Source:

validFormValuesPublishTopic :string

This topic will be published when the form contains valid data
Type:
  • string
Default Value:
  • null
Source:

waitForPageWidgets :boolean

When using the optional auto-saving capability (configured by setting an autoSavePublishTopic) the form will typically need to wait until page setup is complete before allowing automatic saving to commence. However, if a form (configured to auto-save) is dynamically created after the page has been loaded (e.g. when created within a dialog for example) then it this should be configured to be false (otherwise auto-save will not occur)
Type:
  • boolean
Default Value:
  • true
Source:

warnings :object[]

Can be configured to display one or more banners on the form based on the changing value of fields within the form. The configuration is almost identical to that of the visibilityConfig in form fields except that a "message" attribute should also be included that will be displayed when the rules are evaluated to be true.

The default position for the warnings is at the top of the form but it is possible to move the warnings to the bottom of the form by configuring warningsPosition to be "bottom".

Type:
  • object[]
Since:
  • 1.0.32
Default Value:
  • null
Source:
Example

Example configuration for warning displayed when "FIELD1" is set

warnings: [
  {
    message: "Warning 1: Field 1 is not blank",
    initialValue: true,
    rules: [
      {
        targetId: "FIELD1",
        isNot: [""]
      }
    ]
  }
]

warningsPosition :string

This is the position that any warnings will be placed. There are two options available which are "top" (the default) and "bottom". Extending widgets may provide alternative positions.
Type:
  • string
Since:
  • 1.0.32
Default Value:
  • "top"
Source:

widgets :object[]

Type:
  • object[]
Default Value:
  • null
Source:

widgetsAdditionalButtons :object[]

This can be configured with details of additional buttons to be included with the form. Any button added will have the publishPayload set with the form value.
Type:
  • object[]
Default Value:
  • null
Source:

Methods

allWidgetsProcessed()

Makes a call to the validate function to check the initial state of the form.
Source:

createButtons()

Creates the buttons for the form. This can be overridden to change the buttons that are displayed.
Source:

createWarnings()

This function is called to process any warning configuration and create a warning widget to display those warnings.
Since:
  • 1.0.32
Source:

focus()

Focuses on the first field in the form.
Source:

getFormValueDependantOptions(payload)

This function is used to forward on options requests from controls contained within the form. It can be used by setting the "publishTopic" in the "optionsConfig" to be GET_FORM_VALUE_DEPENDENT_OPTIONS. The "publishPayload" in the "optionsConfig" should contain a "publishTopic" attribute that the request should ultimately be forwarded on to. The reason to use this topic is that the forwarded payload will be updated to include the current form value. This makes it possible for options to be generated that are dependant upon changing form values.
Parameters:
Name Type Description
payload object The payload requesting the options.
Since:
  • 1.0.39
Source:

getValue() → {object}

Source:
Returns:
Type
object

onHashChange(payload)

Overrides the implementation from _AlfHashMixin which was written to publish Document Library specific topics. This version responds to the hash change by setting the form value.
Parameters:
Name Type Description
payload object The publication topic.
Source:

onInvalidField(payload)

Handles the reporting of an invalid field. This will disable the "OK" button if it has been created to prevent users from attempting to submit invalid data.
Parameters:
Name Type Description
payload object The published details of the invalid field.
Source:

onOkButtonPublish(payload)

If an okButtonPublishTopic has been provided then this function will be run after it has been published.
Parameters:
Name Type Description
payload object The published payload
Since:
  • 1.0.44
Source:

onRollCall(rollCallObject)

This function is used to register the successful setup of all the form controls. As each form control is added to the page it will publish its value and after the value is published this function will "check it off" from an overall count of all the expected controls. This is done as a final check so that we can be absolutely sure that everything is complete before we allow validation or auto-saving to commence.
Parameters:
Name Type Description
rollCallObject object An object containing a simple count of all the form controls yet to register themselves
Source:

onValidField(payload)

Handles the reporting of a valid field. If the field was previously recorded as being invalid then it is removed from the invalidFormControls attribute and it was the field was the only field in error then the "OK" button is enabled.
Parameters:
Name Type Description
payload object The published details of the field that has become valid
Source:

postCreate()

Source:
Listens to Events:

processWarnings(warnings, warningConfig, index)

Processes an individal warning configuration for the form from the array of warnings that have been configured.
Parameters:
Name Type Description
warnings object[] An array of warnings to push the current warning data into
warningConfig object The configuration for the warning
index number The index of the configuration in the complete array of banners
Since:
  • 1.0.32
Source:

publishFormValidity()

Published the current form validity. This is done as a courtesy for other widgets that might be dependant up the current state of the form.
Source:

publishValidValue()

Source:

reenableOkButton()

Re-enable the OK button after it's been disabled by publishing. Calls the onValidField method to ensure that validation rules are maintained.
Since:
  • 1.0.44
Source:

setHashFragment(payload)

This function is called when useHash is set to true and the OK button is clicked to publish the form data. It will take the value of the form and use it to set a hash fragment.
Parameters:
Name Type Description
payload object The form data to set
Source:

setupOkButtonEnablementSubscription(topic, is, isNot)

Setup the subscription(s) to re-enable the OK button after it's been disabled on submission.
Parameters:
Name Type Argument Description
topic string | module:alfresco/util/objectUtils#Rules The raw topic name to subscribe to, or a Rules object with an additional topic attribute that defines the name of the topic to subscribe to
is string | Array.<string> <optional>
 The possible value/values that will re-enable the OK button if matching the specified attribute
isNot string | Array.<string> <optional>
 The disallowed value/values that will re-enable the OK button if the attribute does not match it/them
Source:

setValue(values, initialization)

Parameters:
Name Type Description
values object The values to set
initialization boolean Indicates whether this call is part of the initialization of the containing form
Source:

submitOkButton()

Execute a form publish as defined by the OK button.
Since:
  • 1.0.49
Source:

updateButtonPayloads()

Update all the button payloads with the supplied values
Source:

updateWarnings(warningConfig, status)

This function is called whenever warning rules have evaluated to indicate a change in visibility for a particular warning.
Parameters:
Name Type Description
warningConfig object The configuration for the warning
status boolean Indicates whether or not the warning should be displayed or not
Since:
  • 1.0.32
Source:

validate() → {boolean}

Source:
Returns:
Type
boolean