Namespace: NWS.Display.FormSupport
Script: /CommonScripts/NWS/Modules.CommonScripts/NWS.Display.FormSupport.js
| Method |
Description |
| init |
Initializes the library based on the supplied params.
params: JSON object providng configuration parameters. Supported parameters:
- requiredScripts - array of paths to additional scripts to load
- fieldConfig - JSON object respresenting field configurations. When provided, configurations applied to fields when on page show. If any fields in the fieldConfig have mask attributes, input mask library automatically loaded
- geoLocationParams - JSON object containing parameters for initializing the NWS.Display.GeoLocationSupport library. If provided, library automatically loaded
- fieldContainer - selector used to restrict scope of fields fieldConfig is applied to
- convertTitanToHTML5 - boolean indicating whether to convert Titan's proprietary validation to HTML5 validation. If true, will use Titan's proprietary attributes to add HTML5 equivalent attributes to the elements
|
| ProcessFields |
Applies supplied fieldConfig to fields within the supplied fieldContainer
fieldContainerSelector: DOM selector string used to scope input fields the fieldConfig will be applied to
|
| ValidateField |
Validates a single form input based on the field configuration for that field.
formField - field DOM element being validated.
|
| ValidateFields |
Validates all input, select, and textarea fields within the supplied field container. If no supplied container, all fields in DOM are evaluated
fieldContainerSelector - sets scope of fields to be evaulated
|
| ConvertCheckboxToRadio |
Converts standard Titan CMS checkbox elements to radio buttons. Allows converting multi-select Tag/Lookup field to a single select radio group. Used in scenarios where the data item being added where you only want to assign one of a multi-select property. The property may be multi-select so that a user can have multiple assigned attributes but data item should only have one (user attribute filtering). There may be other scenarios this is useful.
containerFieldDef - field configuration for the checkbox controls being converted.
defaultValue - allows preselecting a radio button option if one isn't already selected
|
fieldConfig
The fieldConfig is an array off fieldConfig objects that define the field behavior. It controls the following aspects of the field:
- Data source
- Default and Rule Based Validation
- Masking
- Events
[
{
/* optional: friendly description of field, used to more easily identify field when managing the config */
notes: "string"
/* required: id attribute of DOM element corresponding to field */
,fieldID: "string"
/* optional: object representing information for making remote call for JSON data to populate
Expects JSON to return array of name/value pairs (i.e., [ { name:"name", value:"value" }]). name attribute is optional */
,sourceJSON: {
/* required: relative path to JSON file containing data to populate field with. */
path: "string"
/* optional: GET or POST. Default is GET */
,method: "string"
/* parameters required by endpoint being called */
,args:{}
}
/* optional: Data to populate field with. Overrides sourceJSON. Expects array of name/value pairs (i.e., [ { name:"name", value:"value" }]). name attribute is optional Additional as needed by sourceCallback */
,sourceData: {
/* optional: display name for value. Used with select option as the display text for the option. If not provided, value is the display text */
name: string
/* required: value for the input */
,value: string
}
/* optional: function to initailize formField from data. formField parameter is the DOM element identified by the fieldID property. data is determined by the sourceJSON or sourceData properties */
,sourceCallback: function(formField, data) { /* code to initialize formField from data. */ }
/* optional: DOM selector to scope where configuration applied. Most commonly set to "fieldset" */
,parentContainer: "string"
/* optional: Defines how field should be validated. Supports HTML5 validation properties */
,validation: {
/* optional: true - require field, false - do not required field*/
required: boolean
/* See HTML 5 Input Types
Valid values: "text"|"email"|"search"|"phone"|"url"|"numeric"|"slider"|"date"|"datetime-local"|"month"|"time"|"week"|"color"
*/
,type: "string"
/* optional: minimum numerical value for field */
,min: number
/* optional: maximum numerical value for field */
,max: number
/* optional: minimum character length for field */
,minlength: int
/* optional: maximum character length for field */
,maxlength: int
/* optional: regular expression to use for validating field*/
,pattern: "string"
/* optional: callback method if field is valid.
data - object from onValidData property
formField - DOM element corresponding to fieldID of config
*/
,onValid: function(data, formField) { }
/* Object to pass data to onValid callback */
,onValidData: { }
/* optional: callback method if field is invalid.
data - object from onInvalidData property
formField - DOM element corresponding to fieldID of config
*/
,onInvalid: function(data, formField) { }
/* Object to pass data to onInvalid callback */
,onInvalidData: { }
},
/* optional: flag to mark field (and parentContainer, if defined) as disabled. true - disable, false - enable. Default is enabled */
,disable: boolean
/* optional: flag to hide field (and parentContainer, if defined). true - hide, false - show. Default is show. */
,hide: boolean,
/* optional: input mask to apply to field based on https://github.com/RobinHerbots/Inputmask.
Examples:
"(###) ###-####"
"\d+"
"email"
"date"
*/
,mask: "string"
/* optional: flag indicating whether to call NWS.Display.FormSupport.ProcessFields() when the value for the field is changed. This updates other fields based on changes to this field. true - process fields, false - do nothing. Default false. */
,autoProcessEvents: boolean
/* optional: array of events to bind to DOM field corresponding to fieldID */
,events: [{
/* required: DOM event to trigger onRaise method on. Any DOM event supported by DOM element corresponding to fieldID.
Common events: "beforeinput", "change", "click", "blur", "invalid", "focus" */
name: "string"
/* required: method to call when event raised */
,onRaise: function (e) { /* do stuff. */ }
}
]
/* optional: Rules allow redefining properties of field configuration based on conditions, or matched criteria. */
,rules: [{
/* required: criteria for applying rule. All criteria must evaulate to true to apply this rule */
matchCriteria: {
/* optional: field criteria allows applying rule based on value in other fields. Expected array of fieldCriteria objects (e.g., [{ fieldID: "string", pattern:"" }])*/
fieldCriteria: [
{
/* required: id attribute of DOM element corresponding to value */
fieldID: "string"
/* required: regular expression pattern value must match for fieldCriteria to evaluate to true */
,pattern: "string"
}
]
}
/* Add any field configuration property overrides to apply if this rule matches. Example:
, validation { required: true }
, disable:true
*/
}
]
}
]
Implementation
In a Titan CMS 7 instance with NWS Modules.CommonScripts installed, go to the page with the Forms Editor or Data Editor block you would like to apply field rules to.
Go to Page Snippets and add the "NWS Modules.CommonScripts Form Field Rules" snippet to the page:
Add your field configuration to the fieldConfig parameter when prompted.