altersoftware.IT
altersoftware.IT

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

Library index

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:

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.

E.g.:

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:

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:

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:

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:

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:

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:

${} 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.:

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 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:

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":

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:

Adding fields when the form is already rendered

Yes, you can.