:: libs :: js-as-form :: as-form-field

Library index

• js-as-form, AS.form library overview and static methods.
• AS.form object reference.
• AS.form.field object reference.
• AS.form plugins, a list of plugins providing data types and themes
• AS.form events, a list of events triggered by AS.form

AS.form.field object

Each field in AS.form is represented by an AS.form.field object.

Different field types extend the super class AS.form.field.

AS.form.field object methods

Most objects methods are common to every AS.form.field.

asField.disable( [flag] )

Disable both real and AS.form field.

If flag (optional) is false has the same effect of asField.enable()

asField.enable( [flag] )

Remove disabled status (if any) from both real and AS.form field.

If flag (optional) is false has the same effect of asField.disable()

asField.fakeField()

Returns a reference to the fake field used in the fake form.

See also: asField.realField()

asField.getForm()

Returns the AS.form object the AS.form.field belongs to.

asField.getName()

Returns the name of the AS.form.field.

asField.getValue()

Returns the string value of the AS.form.field.

See also: asField.val(), asField.setValue()

asField.hide()

Hides AS.form.field — the field is still there, invisible.

Invoked with false parameter is the same as asField.show()

asField.hideWarning()

Hides asField warning message, if any.

Invoked with false parameter is the same as asField.showWarning()

asField.realField()

Returns a reference to the actual hidden input of the real form.

See also: asField.fakeField()

asField.scrollTo()

Scroll view to field.

asField.setOption( optionName, value )

Sets asField option optionName to value, if defined.

Invoked without value (or with an undefined value) deletes the option.

asField.setValue( v, [skipValidation] )

Sets the string value of the AS.form.field and triggers field validation.

If skipValidation is passed and evaluated true then field validation isn’t performed.

See also: asField.val(), asField.getValue()

asField.show()

Makes AS.form.field visible.

Invoked with false parameter is the same as asField.hide()

asField.showWarning()

Shows asField warning message, if any.

Invoked with false parameter is the same as asField.hideWarning()

asField.val( [v], [skipValidation] )

Get or set field string value.

If v is undefined acts like asField.getValue(), otherwise acts like asField.setValue().

asField.valid()

Returns a boolean if field value is valid depending on its options.

asField.validate()

Checks if field value is valid depending on its options.

In case it is (or isn’t) hides (or shows) the related warning.

Fields options

Common option keys

calc

Function or string: a function whose returning value is evaluated true to validate the field.

When invoked will receive two parameters: field value, field reference.

If string, can be:

• A global (window) function name
• The serialization of an arrow function, e.g: (value,field)=>{ value >= field.getForm().getField('another').getValue(); }
• Javascript code interpolated, compiled and executed. See notes about interpolation.

customWarning

String: a static string to be displayed at the beginning of validation failure warning.

default

Field default value, defaults to value or empty string.

depends

String: field(s) conditon(s) current field depends on: it will be hidden and disabled if the condition(s) is/are true.

• Can check if the field exists, is enabled and has non-empty/non-zero value with fieldname.
• Can check if the field exists and is enabled, regardless of value, with (e)fieldname.
• Can check for actual field value, case sensitive: fieldname=value.
• Can check for field value including a word, case insensitive: fieldname=~word
• Can invert the single check with a leading “!”: !fieldname, !(e)fieldname, !fieldname=value, !fieldname=~word.
• In case current field depends on multiple conditions:
  • If they’re in OR separe them with a double pipe (||): the test will be true if at least one condition matches.
  • If they’re in AND separe them with && or with a comma ,: the test will be true if all conditions match.

E.g.:

• depends="!fieldalternative"
• depends="(e)relatedfield"
• depends="(e)choice1||!choice2=Yes"
• depends="!(e)choice1&&choice2=~no"
• depends="!choice1=A,!choice1=B,(e)choice2"

Please note:

1. depends can be used on control fields, but can only check for real fields (not control fields) except for the (e)fieldname enabled test. This because control fields value is never reported in actual form data.
2. Fields can depend one from the other.
3. AS.form code prevents loops, then in case you create a loop the behavior is likely to be incomplete.

disabled

Boolean: if evaluated true the field will be disabled.

expr

Function or string: a function whose returning value is evaluated true to validate the field.

When invoked will receive two parameters: field value, field reference.

If string, can be:

• A global (window) function name
• The serialization of an arrow function, e.g: (value,field)=>{ value >= field.getForm().getField('another').getValue(); }
• Javascript code interpolated, compiled and executed. See notes about interpolation.

help

String: field help. Can be a URI (starts with http:// or https://) or a free text.

If URI will open in a new window (always the same), otherwise becomes the title attribute of the help sign.

hidden

Boolean: if evaluated true the field will be hidden, defaults to false.

id

String: the ID of the field, defaults to autogenerated ID.

iscontrol

Boolean: if evaluated true no real field will be generated.

When using iscontrol:

• asField.getValue() is undefined, to get fake field value use asField.fakeField().value
• validation is always true, unless override is in place.
• onchange and other methods receive fake field value, not undefined.

label

String: the label for the field, defaults to field name

labelclass

String: an additional class (or more space separated classes) to be added to label node.

labelwidth

String (or integer for px): forced label width.

Defaults to automatic (or form-defined) width.

Note: this setting is ignored on mobile devices, where labels are presented in full-width.

mandatory

Boolean: if evaluated to true the field becomes mandatory (not disabled, non-empty value).

nolabel

Boolean: if evaluated true this label won’t be created.

nowarning

Boolean: if evaluated true this warning message won’t be created.

onchange

Function or string: triggered on field change.

When invoked the function receives two parameters: field value, field reference.

If string, can be:

• A global (window) function name
• The serialization of an arrow function, e.g: (value,field)=>{ field.getForm().getField(value).hide(); }
• Javascript code interpolated, compiled and executed. See notes about interpolation.

override

Function or string: triggered on field change, if evaluated true field is valid - not valid otherwise.

Overrides whatever else validation control (e.g.: mandatory, calc, expr), including custom validation controls specific to the field (e.g.: min/max for integer and strings).

If string, can be:

• A global (window) function name
• The serialization of an arrow function, e.g: (value,field)=>{ field.getForm().getField(value).hide(); }
• Javascript code interpolated, compiled and executed. See notes about interpolation.

position

String: field position area, see: Fields positioning

re

String: a regular expression the field value must match to validate.

Can be interpolated, see notes about interpolation.

skipempty

Boolean: if evaluated to true the field won’t be reported in form data if empty.

tab

Integer: tab number the field belongs to, in case of position:"tabs".

See: Fields positioning

transform

Function or string: when setting value if value is a string it can be transformed by this function.

When using transform don’t forget that when values are parsed again they’ll be rendered back in the field using String(value).
Then: a string remains unchanged, a plain array becomes a comma-delimited string, an object becomes [object Object].

When invoked the transform function receives two parameters: field value, field reference.

If string, can be:

• A global (window) function name
• The serialization of an arrow function, e.g: (value,field)=>value.split(/ *[;,] */)
• Javascript code interpolated (like in expr), compiled and executed, e.g.: ${}.split(/ *[;,] */). See notes about interpolation.

validateFields

String, comma separated: a list of other fields that should be validated when validating this field, useful when you reference also other field values in calc, expr, func, override or re options.

Be very careful: don’t create infinite loops, that could freeeze the window.

value

Field initial value, defaults to default or to empty string.

Notes

When field name is an empty string a fake automatic name is generated.
In this case field options iscontrol and nolabel are automatically set to true

Interpolation

calc, expr, override, re, onchange, transform options can be written using this notation:

• ${} to be replaced with actual field value, or empty string
• ${fieldname} to be replaced with actual field fieldname value, or empty string (or 0 for calc)
• $% to be replaced with actual asForm object, e.g.: $%.setTheme(${})

${} and ${fieldname} expressions when missing or empty are replace with an empty string (or 0 for calc).

In calc option ${} and ${fieldname} expressions when missing or empty are replace with 0 (zero). E.g.:

• ${totalAmount} > ${partialAmount}
• ${} == parseInt(document.getElementById('foo').innerHTML)
• window.myBooleanFunction(${},${anotherField})

That's enough about re, it’s just interpolated.

Interpolation becomes compilation

Now see what else happens with options (like calc, expr, override, onchange, transform) that are functions: they’re compiled

E.g.:

onchange="$%.setTheme(${})"

// is dynamically compiled to:

onchange="(fieldValue,fieldObject)=>{\nlet formObject=fieldObject.getForm();\nlet emptyValue=\"\";\nreturn (formObject.setTheme(formObject.fieldValue(fieldObject,emptyValue)));\n}"

// which is:

(fieldValue,fieldObject)=>{
    let formObject=fieldObject.getForm();
    let emptyValue="";
    return (formObject.setTheme(formObject.fieldValue(fieldObject,emptyValue)));
}

• The serialization of an arrow function is run, receiveng the usual parameters:
  1. Field value
  2. Field reference
• In order to retrieve the value of fields the compiled arrow function uses the asForm.fieldValue() form method, that retrieves also control field values and allows to replace a missing/non-existing/empty/zero/false/disabled field value with an alternative emptyValue.
• In case of arrays, objects, boolean and numeric values the raw value (Array, Object, Boolean or Number) is returned, rather than its JSON serialization.

The original original expression is between parenthesis after “return”, $% and ${} replaced by their actual javascript code counterparts.

E.g.:

expr="${}.length == ( parseInt(${fieldA})||parseInt(${fieldB}) )"
// =>
(fieldValue,fieldObject)=>{
    let formObject=fieldObject.getForm();
    let emptyValue="";
    return (
        formObject.fieldValue(fieldObject,emptyValue).length
        ==
        (
            parseInt(formObject.fieldValue("fieldA",emptyValue))
            ||
            parseInt(formObject.fieldValue("fieldB",emptyValue))
        )
    );
}

calc="parseInt(parseFloat(${})*100) >= parseInt(${anotherField})"
// =>
(fieldValue,fieldObject)=>{
    let formObject=fieldObject.getForm();
    let emptyValue=0;
    return (
        parseInt(parseFloat(formObject.fieldValue(fieldObject,emptyValue))*100)
        >=
        parseInt(formObject.fieldValue("anotherField",emptyValue))
    );
}

transform="${}.replace(/[ \r\n\t]+/g,' ').split(/[,; ]+/).filter(c=>c.length).join(',')"
// =>
(fieldValue,fieldObject)=>{
    let formObject=fieldObject.getForm();
    let emptyValue="";
    return ( formObject.fieldValue(fieldObject,emptyValue).replace(/[ \r\n\t]+/g,' ').split(/[,; ]+/).filter(c=>c.length).join(',') );
}

Please note that if you use an arrow function it will not be interpolated at all:

onchange="(x,f)=>{if(x)f.getForm().setValue('anotherField',x.length)}"
// =>
(x,f)=>{
    if(x) f.getForm().setValue('anotherField',x.length);
}

// While:

onchange="(x,f)=>{if(x) $%.setValue('anotherField',x.length)}"
// => ERROR!
// “Error: SyntaxError: Unexpected token '.'”

// This happens because by recognizing the presence of an arrow function
// the “onchange” attribute is NOT interpolated, and “$%” remains unchanged.

Validity chain

Validity check chain stops at the first false respose.

Sequence is:

• in case of override whatever else control is ignored.
• otherwise:
  1. Specific field contrains (e.g: format, min, max etc )
  2. mandatory, if requested
  3. re, if any
  4. calc, if any
  5. expr, if any
  6. Eventually valid, if none of the above tests failed.

Why a custom warning

When using calc, expr, override or re don’t forget to provide also a customWarning string option to make clear what went wrong diring validation.

You’re asked to localize such string according to the page, possibly using js-as-labels

Fields positioning

Normally fields are positioned one after the other according to entry order, and that’s typically enough.

On the other hand it’s possible to group them together and define custom positioning, using options position and tab in field options — and optionally tabs in form options.

Overall schema:

    +---------------------------------------------------+
    |                    Title area                     |
    +---------------------------------------------------+
    |                                                   |
    |   no position or position:"top", by entry order   |
    |                                                   |
    +---------------------------------------------------+
    |    Tab bar, automatically generated if needed     |
    +---------------------------------------------------+
    |                                                   |
    |                                                   |
    |               position:"tabs", tab:…              |
    |                  by entry order                   |
    |                                                   |
    |                                                   |
    +---------------------------------------------------+
    |                                                   |
    |          position:"bottom", by entry order        |
    |                                                   |
    +---------------------------------------------------+

It’s quit easy to understand the use of position:"top" (or no position) and position:"bottom".

Let’s focus on position:"tabs":

• When a field uses position:"tabs" (or has tab:integer option) it’s automatically allocated in the middle tabs area.
• Field tab option (integer) determines the tab the field belongs to
• Field tab option can also be an integer value in a string, e.g.: tab:"2"
• A field with position:"tabs" and without tab option defaults to tab:0
• A field with tab:integer and without position option defaults to position:"tabs"
• Tabs are defined by a positive integer number, not necessarly in sequence, 0 or bigger.
• Tabs will be presented in the tab bar in ascending tab number order
• The existing tabs are automatically determined by AS.form while adding fields
• Inside each tab fields belonging to the tab are represented in entry order

Where there is only one tab the tab bar will be empty.

Tabs with labels

When the tabs are represented by labels also one only tab label will appear in the tab bar.

In order to represent labels on the tab bar we can use the tabs option in form options.

Form tab option can be:

1. An array of strings (at least as long as the number of tabs determined by fields)
2. A string semicolon-delimited, resulting in the above array.
3. A string comma-delimited, resulting in the above array.

Let’s say that in fields you used position:"tabs" with tab attributes 100, 11, 350:

• Three tabs will be generated, their order will be: 11, 100, 350.
• If you provided at least three labels in tabs form options, they’ll be used in this order.
• If labels are less than actual tabs amount, the labels will be ignored.

Adding fields when the form is already rendered

Yes, you can.

• If the field belongs to an existing position (or tab) it will be rendered at the bottom ot its position (or tab)
• If the field belongs to a tab or position that doesn’t exist the area or position will be created automatically
• Tab bar is automatically updated
• In case of new tab creation, if labels were used, the tabs will fall back to unlabelled tabs if labels aren’t enough.

© 2009 altersoftware.IT - I marchi citati sono © dei rispettivi proprietari.

© 2009 altersoftware.IT - Cited marks © by respective owners.