Module buildForm

Last change: March 4, 2021

Current version: 1.55.15

The buildForm module allows you to create forms on your page. It comes with many features:

different field types
HTML 5 compatible
required fields
input suggestions
auto hide and show of fields
more ...

syntax

webanizr.send('buildForm', formmodel, parameters, callback)

The buildForm module takes a json model as input for creating a form. Most common use is to retreive the model from an online source using the callAPI module:

webanizr.collect('callApi', { url__api : '/mymodels/formmodel.json' }, (data) => {
    webanizr.send('buildForm', data, { id__dom : 'myformdiv', id__form : 'myform' });
});

formmodel

The model then is used by the buildForm consists of two parts:

{
    "model" : {
    },
    "configuration" : {
    }
}

The "model" part describes the fields to be shown in the form. The "configuration" part contains addition information for the form itself, eg. the submit button text.

model (required)

The model has an element for each field to be displayed in the form:

{
    "model" : {
        "person__firstname" : {
            "field__name" :         "person__firstname",
            "form__label" :         "First name",
            "field__required" :     true,latest
            "field__type" :         "shorttext",
            "field__datalist" :     ["Peter", "Ron", "John"],
            "field__placeholder" :  "eg. Peter",
            "help__hint" :           "Some help hint for firstname field"
        },
        "person__email" : {
            "field__name" :         "person__email",
            "form__label" :         "E-mail address",
            "field__required" :     true,
            "field__type" :         "shorttext",
            "field__placeholder" :  "eg. peter@whereismyemail.com"
        }
    },
    "configuration" : {
        ...
    }
}

Although it is common to use the name of the field as key for each field element. Each field element can have the following attributes:

field__name (required)

The name for the form field. The value of this attribute is placed in the name attribute of the DOM element that is created.

form__label (optional)

A form label to be shown with the field. The form label describes to the user what input is expected in the corresponding field.

field__required (optional)

If set to true, the visitor is required to fill in this field before the form can be submitted

field__type (optional)

The type of field to be created. Allowed values for this attribute are:

shorttext: creates a short text input field
image: creates an file upload field
file: creates an file upload field
select: creates a dropdown with options
text: creates a text area input field
checkbox: creates a checkbox
username: creates a short text input field with the attributes to correctly support Google Chrome autofill
password: creates a password field
email: creates a shorttext field for email addresses
hidden: creates an hidden field
number: a shorttext field for numbers
tinymce: add a TinyMCE editor
quill: add a Quill editor
ckeditor: add a CKEditor
recaptcha : add a Google Recaptcha checkbox
togglevar: add a text button that toggles a webanizr var on / off
description: ads a description text. The text is taken from the value of the field__value parameter. This field is not interactive.
date: HTML5 date field
datetime-local: date and time field consists of 6 fields.
date-selects: a date field consisting of 3 selects
datetime-selects: date and time field consists of 6 select fields(5 if include__second is set to false in config)
draganddropfile: a file field you can drag and drop fields to

If no field__type is given, a shorttext field will be created.

field__placeholder (optional)

A placeholder text to be shown untill the visitors inputs a value in the form field. Placeholders only work on text based form fields.

max__filesize (optional // only on drag and drop)

Maximum file size to upload(has to be specified in KB).

warning__filesize (optional // only on drag and drop)

Warning message to show on the form if the uploaded file size exceeds the allowed limit(max__filesize).

help__hint (optional)

If this field is filled, a question mark icon will appear near the form field and the text value of help__hint will shown inside a text balloon when the question mark icon is clicked.

help__docs (optional)

If this field is filled, a question mark icon will appear next to the label. The value of this attribute should be an array with the ids of the relevant documentation. When clicked on the icon a popup will be shown with the content of these articles.

now__value (optional)

Boolean value. If true, sets the initial date to current date.

field__datalist (optional for select input fields)

A list of the options to be shown as suggestions. Only works with input type fields.

selectoptions (required for select type fields when sourceoptions is not used)

A key-value list of the options to be show. Only works with select type fields. These options can be formed in two different formats:

{
    "one" : "label for option one"
    "two" : "label for option two"
}

{
    "one" : {
        "value__option" : "one",
        "label__option" : "label for option one",
        "src__icon" : "https://somewhere.com/myimageone.png",
        "data__option" : { myvar : "one" }
    },
    "two" : {
        "value__option" : "two",
        "label__option" : "label for option two",
        "src__icon" : "https://somewhere.com/myimagetwo.png",
        "data__option" : { myvar : "two" }
    }
}

The src__icon will be used by radio buttons to add an image to the option. The data__option adds a data-webanizrvars attribute to the option with the stringyfied data in select options.

source__options (optional for select type fields)

The database name of the dataset you want to use as an option list. The options are fetched from the headless API of Webanizr. This option will therefor only work in Webanizr websites.

run__onchange (optional)

A script to be executed when the value in the field loses focus (i.e. by going to the next field in the form) and the value has changed.

source__options (optional)

The name of the dataset to use as options for a select or radio buttons. The options will be retreived from an API call.

label__nulloption (optional)

The label of the option with an empty string as a value. This value is only applicable for options in a list.

advanced__selectoptions (optional)

When used in combination with source__options the API will give the more advanced set of options. One of the applications is to generate radio buttons with images.

mode__newlines (optional)

When set to true in radion buttons, each label will get the css class "multiline". This class can be used to place each label on a new line.

token__security (optional)

The security token to use to retreive the options with source__options.

run__onfirstchange (optional)l

A script to be executed when the value in the field changes.

field__value (optional)

The initial value to set the field to.

hideon__script (optional)

The script that dictates when the field will be shown or hidden.

section__data (optional)19

The section this fields belongs to. The section can be used to only show a part of the complete model (see section__data in the parameters section on this page).

value__script (optional)

Sets an script which changes the value of this field when the associates variable changes. If this parameter is set to "parseInt(any__number) + 3" and the cp variable is set to 5 the value in this field will change to 8.

type__display (optional)

If set to "toggle" on checkboxes, the label will get the classname "toggle". You can use this class to style the checkbox as an toggle.

validations__value (optional)

This parameter adds validations to the field. As value you should supply an array with validations. Each validation is a JSON object with the following parameters describing the validation:

type__validator (required): either html5 or webanizr. The first option adds regular html5 validations to the field. The second adds custom webanizr validations.
type__validation (required): the type of validation to be performed. The following types are supported:
- pattern (html5 and webanizr): test the value against a regular expression
- minlength (html5): test if the value has a minimum number of characters
- maxlength (html5): test if the value has a maximum number of characters
- min (html5): test if the value is not lower then the given value
- max (html5): test if the value is not higher then te given value
value__validation (required for most types): the value to compare the field value to. Ie. the minimum value in the min test or the regular expression in the pattern test.
message__invalid (requried for webanizr validation): the message to show the user when the test is not passed.

name__class (optional)

An extra css class that is given to the field wrapper div.latest

November 27onchange__formstate (optional)

Sets the form state to the given state as soon as any changes are done to the value of this field. Possible options for the form state are:

changed
send (sends the form)

name__var (required for togglevar field)

The name of the webanizr variable that will be turned on / off.

nr__columns (optional)

Sets the number of columns this field spans. If not set, it will span all columns. This parameter will only work when the nr__colums in the configuration is set.

config__toolbar (optional for ckeditor fields)

See the ckEditor module documentation for more information.

delayed__ckeditor (optional for ckeditor fields)

If set to true, adds a CKEditor and load it only when the field is clicked. This is false by default.

preset__toolbar (optional for ckeditor fields)

See the ckEditor module documentation and/or the example demo for more information. Possible options for preset__tooblar:

description

mode__multiplefiles (optional)

If set to true, the draganddropfile fieldtype wil support uploading multiple files. This is false by default.

multiplefiels__messages (optional)

The text to display in a draganddropfile fieldtype when more then one file is uploaded. The placeholder {count} will be replaced with the number of files. If not set, this will default to "{count} files selected".

nomultiple__messages (optonal)

The text to display when more then one file is dragged to a draganddropfile when this is not allowed. If not set, this will default to "No more then one file allowed".

Configuration (optional)

The model defines additional attributes to the form:

{
    "model" : {
        ...
    },
    "configuration" : {
        "submit__label" :           "Test",
    }
}

The following parameters can be used in the configuration section:

submit__label (optional)

The text to be displayed on the submit button

nr__columns (optional)

Set the layout of the form to the given number of columns. To be used with the nr__columns parameter in fields.

mode__requiredlabels (optional)

If set to "required" or "notrequired" it will append text to all labels for required or not required fields.

text__requiredlabels (optional)

If used in combination with mode__requiredlabels. this parameter defines the text to add to the labels.

type__loadingdata (optional)

Tells the form to load the values for in the fields from the data model. The value for this attribute should be a type that exists in the datamodel

context__loadingdata (optional)

Can be used in combination with type__loadingdata. It supplies the data model with additional information to get the right data

tokenloadingdata (required when using typeloadingdata)

The security token that allows you to retreive the requrested data

include__seconds (optional)

Toggles second field in datetime-selects, true by default. If set to false the second value will be 00 and date-selects field will contain 5 dropdown fields.

dataname__mustache (optional)

Adds a mustache name to the formid. Nescerry and only usefull when the form is used in a mustache template. Setting this setting will also cause some javascript functions to be added inline.

You only need to supply de dataname. Curly braces will be added by the plugin.

set__fields

Places this field inside inside a fieldset element. The value of this parameter will be used as label of the fieldset. If more fields with this value follow, they will all go in this fieldset.

parameters

The buildForm module has two parameters than can be used:

id__dom (required)

The id__dom parameters tells the module in what DOM element the form should be placed. The farm is added as content to this element: if there is already content in the element it will not be replaced.

id__form (required)

the id__form parameters tells the module what HTML id the form should have. This id can be used in conjunction with the formValues module to get the values after submit.

section__data (optional)

Defines the data section of the model of whicuh the fields should be added. If this attribute is set, only fields that have the section__data attribute and match the value of the section__data parameter are added to the form.

type__placement (optional)

Tells the modue how to add the form to the dom element. There are two options:

add: adds the form add the bottom to the exists content (default)
replace: replaces the current content with the form

If this parameter is ommitted, the default option is used.

enable__globalvars (optional)

If this parameter is set to true: the module will use variables set with cp.setVars as values in the form if there names match the names of the fields.

onlyfields__form (optional)

If this parameter is set to true, a div element is set as container element for the fields instead of a form element. You can use this option to create a form with multitple models. If you create the form element yourself in the html, you can use multiple calls to buildForm to combine al models. If you set an html id to your form element, you can use formValues to collect the data of all model fieldss combined.

form__values (optional)

Initial values for the form. The value for this parameter is a key-value list. The key should be te name of the field where the value should be the value you want to assign to this field.

classname__form (optional)

The classname for the form. If this parameter not is set, the classname mdform is used.

hidden__sbumit (optional)

If set to true, the submit button wil be hidden using the html hidden attribute.

attributes__submit (optional)

Adds data attributes to the submit button. E.g. when the value { cphidden : "state__demoform != 'changed'" } is used, the submit button is hidden when the variable state__demoform is anything other then 'changed'.

translate__form (optional)

If set to false, doesn't translate the form.

Note: The default option for translating a form is true.

hidden__label (optional)

If set to true, hides the label of the form field. It hides the specified label only visually, so that not having a label for a form field doesn't affect the lighthouse accessibility score.

disabled__field (optional)

If set to true, the field will be disabled and wont allow to enter any value. The fields are not disabled by default.

field__focus (optional)

The name of the field to put focus on when the form is loaded. Does not work correct for radio buttons.

callback

The callback function is called once the construction of the form on the page is finished. As data is passes the data it used for constructing the form without alterations.

demo

Build a form:

https://cdn.cpmodules.webanizr.com/demo/build-form/index.html

Required fields:

https://cdn.cpmodules.webanizr.com/demo/required-fields/index.html

Form validations:

https://cdn.cpmodules.webanizr.com/demo/form-validations/index.html

Help hints:

https://cdn.cpmodules.webanizr.com/demo/form-help-hints/index.html

Feedback text on click submit form button:

http://localhost:2080/demo/feedback-submit-button/index.html

changelog:

March 5, 2021 - 1.59.0 Changed the label to legend for datetime selects
March 5, 2021 - 1.55.15 - Set the delayedckeditor as a parameter of ckeditor as delayed__ckeditor
March 3, 2021 - 1.55.14 - Added delayedckeditor new form field type
March 2, 2021 - 1.55.13 - Fix run__onchange bug on multicheckbox field
December 8, 2020 - 1.55.4 - Updated the values of multicheckbox into a proper json format
December 8, 2020 - 1.55.4 - Added multiple use of multicheckbox in a form
December 8, 2020 - 1.55.3 - ???
December 8, 2020 - 1.55.2 - ???
December 8, 2020 - 1.55.1 - ???
December 8, 2020 - 1.55.0 - ???
December 8, 2020 - 1.54.10 - ???
December 8, 2020 - 1.54.9 - ???
December 8, 2020 - 1.54.8 - ???
October 15, 2020 - 1.54.7 - Bug fix on checkbox field
October 12, 2020 - 1.54.6 - ???
October 12, 2020 - 1.54.5 - ???
October 12, 2020 - 1.54.4 - ???
October 12, 2020 - 1.54.3 - Fixed edge case bug on drag and drop field
October 8, 2020 - 1.54.2 - Added maximum item size on drag and drop field
September 26, 2020 - 1.54.1 - Date selects fields now also accepts negative timestamps as value
September 21, 2020 - 1.54.0 - Labels and field change order if window.wcag is set to 2 or higher
September 15, 2020 - 1.53.0 - Added disabled field option to possible fields
September 8, 2020 - 1.52.1 - Fixed order of fields when using fieldsets
September 7, 2020 - 1.52.0 - Added feldsets
August 30, 2020 - 1.51.11 - Fixed issues with ckEditor
August 16, 2020 - 1.51.8 - Fixed issue with required drag and drop fields
August 8, 2020 - 1.51.6 - Updated dependency on codeMirror to 1.1.3
July 25, 2020 - 1.51.5 - Added help hint support to checkbox field
July 25, 2020 - 1.51.4 - ???
July 25, 2020 - 1.51.3 - Dependency update (to use newer version of ckeditor)
July 23, 2020 - 1.51.2 - Dependency update (to use newer version of ckeditor)
July 22, 2020 - 1.51.1 - Dependency update (to use newer version of ckeditor)
July 16, 2020 - 1.51.0 - Added the help__docs attribute
July 13, 2020 - 1.50.3 - Updated the version number of ckeditor
July 13, 2020 - 1.50.2 - Fixed onchange bug whiched caused a fatal error
July 10, 2020 - 1.50.1 - Support for existing values for the drag and drop field type
July 10, 2020 - 1.50.0 - Added experimental parameter dataname__mustache to the configuration
July 3, 2020 - 1.49.1 - Click to select file now also shows the filename in drag and drop field
Jun 19, 2020 - 1.49.0 - Added dradanddropfile fieldtype
Jun 18, 2020 - 1.48.2 - Fixed label issue for checkboxes
Jun 17, 2020 - 1.48.1 - value__script now also works when the value was set before the form was build
Jun 6, 2020 - 1.48.0 - Added the field__focus parameter
Jun 6, 2020 - 1.47.4 - If no label is set for a checkbox it no longer displays "undefined"
Jun 3, 2020 - 1.47.2 - Fixex bug in datetime-selects second field.
May 25, 2020 - 1.47.2 - Fixed years__future and years__past bug when the selected/prefilled year exceeds the years__future or years__past the data was lost. And fixed hour, minute, second empty value bug.
May 25, 2020 - 1.47.1 - Fixed the bug on datetime-selects, when second value is set to 0 it resets all fields and fixed now__value prefilling bug
May 25, 2020 - 1.47.0 - Added datetime-selects field to select date and time via 5 or 6 select field
May 21, 2020 - 1.46.0 - Added datetime field to select date and time via datepicker
May 19, 2020 - 1.45.0 - Added form data in lodaded__pagedata webanizr var
May 16, 2020 - 1.44.10 - ??
May 16, 2020 - 1.44.9 - ??
May 16, 2020 - 1.44.8 - Value script now also works for codeMirror fields
May 6, 2020 - 1.44.8 - Initial number of days are 31 on 3 field date-select.
May ?, 2020 - 1.44.7 - ???
May ?, 2020 - 1.44.6 - ???
May 2, 2020 - 1.44.5 - Fix onchange for multicheckbox
March 24, 2020 - 1.44.2 - Email field will always do a strict check, the same as webanizr does
March 12, 2020 - 1.44.1 - Removed error messages on min and max html5 value validations
March ??, 2020 - 1.44.0 - ???
March 9, 2020 - 1.43.2 - Updated the required version of ckEditor to 1.3.3
March 5, 2020 - 1.43.2 - Updated the required version of ckEditor to 1.3.2
March 4, 2020 - 1.43.1 - Updated the required version of ckEditor to 1.3.1
March 4, 2020 - 1.43.0 - preset_toolbar now also works for ckEditors firelds
February 28, 2020 - 1.42.2 - Run on first change now also works for ckEditors
February 26, 2020 - 1.42.1 - Fixed dependency incompatibility
February 19, 2020 - 1.42.0 - Added hidden labels for each field on 3 date selectors.
February ??, 2020 - 1.41.2 - ??
February ??, 2020 - 1.41.1 - ??
February ??, 2020 - 1.40.4 - ??
February ??, 2020 - 1.40.3 - ??
February ??, 2020 - 1.40.2 - ??
February ??, 2020 - 1.40.1 - ??
January 27, 2020 - 1.40.0 - Added hidden__label option
January ??, 2020 - 1.39.2 - ??
January ??, 2020 - 1.39.1 - ??
January ??, 2020 - 1.39.0 - ??
January 7, 2020 - 1.38.13 - Added ids to fields and for atttribute to labels
January 6, 2019 - 1.38.12 - Visited fields get class "visited", after submit click all fields get class "visited"
December 6, 2019 - 1.38.10 - Fixed typo in years__future and years__past
December 6, 2019 - 1.38.9 - Fixed the bug that ignores the configuration when years__future and/or years__past is set to 0.
December 5, 2019 - 1.38.8 - ??
December 4, 2019 - 1.38.7 - Fixed dayfieldname is not found error.
December 3, 2019 - 1.38.6 - Fixed the bug that always showing 28 days at the beginning on the day field of 3 field date-selects.
December 3, 2019 - 1.38.5 - Added years__past and years__future to present years on 3 field date-selects.
December 2, 2019 - 1.38.4 - Fixed webanizr type of type__validator pattern check.
November 27, 2019 - 1.38.3 - Fixed the date-selects field
November 27, 2019 - 1.38.2 - Fixed crash when there was no configuration in the model
November 27, 2019 - 1.38.1 - Value of parameter context__loadingdata in the form configuration now parser webanizr variables
November 26, 2019 - 1.38.0 - Added the option to buildForm to retreive data from the datamodel
November 18, 2019 - 1.36.1 - Fixed problem with date fields when multiple forms with the same name for the date field are or one page
November 7, 2019 - 1.36.0 - Added translate__form parameter to whether or not translate the form
November 5, 2019 - 1.35.0 - Optional feedback text on click submit form button
November 1, 2019 - 1.34.0 - Help hints with an icon beneath the fields are available now
October 24, 2019 - 1.33.1 - Fixed typo in label marking
October 24, 2019 - 1.33.0 - Label marking for required or optional fields
October 23, 2019 - 1.32.2 - Now uses the correct date format for in- and output in date select fields
October 23, 2019 - 1.32.1 - Date-selects now also supports the field__required parameter
October 23, 2019 - 1.32.0 - Added the displaytype option to checkboxes
October 23, 2019 - 1.31.0 - Added the multiline option to radion buttons
October 21, 2019 - 1.30.6 - Empty field for select option fixed
October 21, 2019 - 1.30.5 - ??
October 7, 2019 - 1.30.4 - remove console.log that was left from testing
October 7, 2019 - 1.30.3 - auto translate for messages in invalidations
October 5, 2019 - 1.30.1 - auto translate for labels in radio buttons
October 3, 2019 - 1.30.0 - auto translate submit button, labels and placeholders if the translate module has started
September 18, 2019 - 1.29.1 - set the correct dependency for sendToAPI
September 17, 2019 - 1.29.0 - added support for the security token
September 17, 2019 - 1.28.1 - added support for advanced options when retreiving from API
September 17, 2019 - 1.28.0 - added the src__icon parameter for radio button options
September 13, 2019 - 1.27.6 - onchange now works for date-selects
September 13, 2019 - 1.27.5 - prefill value for date-selects now works correct
September 12, 2019 - 1.27.4 - run onfirstchange can now access the field by using the 'field' variable in buildForm
September 12, 2019 - 1.27.3 - fixed debounce for textarea's
September 12, 2019 - 1.27.2 - fixes for the date-selects field and radio button can now be required
September 12, 2019 - 1.27.1 - date-selects field type now processes initial values
September 11, 2019 - 1.27.0 - added the date-selects field type
September 10, 2019 - 1.26.2 - added css classes to radio buttons
September 10, 2019 - 1.26.1 - restructered the html build of radio buttons
September 5, 2019 - 1.26.0 - added the config__toolbar parameter for ckEditor fields
September 5, 2019 - 1.25.0 - added the description field
August 20 - 1.22.0 - added layout functions (nr__columns)
August 1 - 1.17.0 - support for datalist in input textfields to offer suggestions
July 11 - 1.14.0 - field file type added

Webanizr is a product of Content Power

syntax

formmodel

model (required)

field__name (required)

form__label (optional)

field__required (optional)

field__type (optional)

field__placeholder (optional)

field__datalist (optional for select input fields)

select__options (required for select type fields when source__options is not used)

source__options (optional for select type fields)

run__onchange (optional)

source__options (optional)

label__nulloption (optional)

mode__newlines (optional)

token__security (optional)

run__onfirstchange (optional)l

field__value (optional)

hideon__script (optional)

section__data (optional)19

value__script (optional)

type__display (optional)

validations__value (optional)

name__class (optional)

An extra css class that is given to the field wrapper div.latest

November 27onchange__formstate (optional)

name__var (required for togglevar field)

nr__columns (optional)

config__toolbar (optional for ckeditor fields)

delayed__ckeditor (optional for ckeditor fields)

If set to true, adds a CKEditor and load it only when the field is clicked. This is false by default.

preset__toolbar (optional for ckeditor fields)

mode__multiplefiles (optional)

nomultiple__messages (optonal)

Configuration (optional)

submit__label (optional)

nr__columns (optional)

mode__requiredlabels (optional)

text__requiredlabels (optional)

type__loadingdata (optional)

context__loadingdata (optional)

token__loadingdata (required when using type__loadingdata)

include__seconds (optional)

set__fields

parameters

id__dom (required)

id__form (required)

section__data (optional)

type__placement (optional)

enable__globalvars (optional)

onlyfields__form (optional)

form__values (optional)

classname__form (optional)

hidden__sbumit (optional)

attributes__submit (optional)

translate__form (optional)

hidden__label (optional)

disabled__field (optional)

field__focus (optional)

callback

demo

changelog:

selectoptions (required for select type fields when sourceoptions is not used)

tokenloadingdata (required when using typeloadingdata)