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

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 object

AS.form is a class, create a new object with new AS.form({ options… }).

Static methods are listed here

New object options

options is an optional Javascript object in the form { key: value, ... }

Allowed keys (all of them optional):

• action (URI): form action, defaults to no action (same URI of the page).
• effectduration (integer): the duration (in mSec) of animated transitions, set to 0 (zero) for no transitions. Defaults to 500 (half a second).
• id (string): the ID of the real form, autogenerated otherwise.
• jsaction (Function object or string): a javascript function invoked on submit, while actual submit is ignored regardless of method.
  When invoked will receive two parameters: JS form data, form reference.
  If string, can be:
  • A global (window) function name
  • The serialization of an arrow function, e.g: (data,form)=>{ doSometing(data); form.destroy(); }
• labelclass (string): an additional class to be added to labels.
• labelwidth (string or integer for px): default labels width for the form.
• method (string): form method, defaults to POST. Use NONE to prevent submit.
• onchange (string or function): invoked when form changes, receives JS form data and a reference fo asForm object.
• onsubmit (string or function): invoked on fake form submit if asForm validates, for additional custom validation.
  Receives JS form data and a reference fo asForm object.
  Return a boolean true value if submit should proceed.
• nolabels (boolean): if evaluated as true form labels won’t be created.
• subforms: see subforms for details.
• subparts: see subparts for details.
• tabs (Array or string): the string (semicolon or comma delimited), or the array, with tab names. See: Fields positioning
• theme (string): the color theme for the form. Defaults to transparent;
• width (string or integer for px): form fixed width.

Note that both labelwidth and width are ignored on small screens (e.g.: mobile).

Themes

Color theme can be choosen at creation time, or later on using asForm.getTheme() and asForm.setTheme().

Transparent is the default theme, black on transparent

as-form-basic provides also themes:

• Light (light) - black on light grey
• Cyan (cyan) - black on light cyan
• Black (black) - light grey on very dark grey

Object methods

Create a new object with let asForm = (new AS.form( options )).

asForm.addField( name, type, [options] )

Add a field to the form, returns the asForm object.

If you want to retrieve asField object use asForm.getField( fieldName )

Parameters:

1. name (string, mandatory): the name of the field, must be unique in a form
2. type (string, mandatory): the type of the field, defined by some plugin
3. options (key/value object, optional): parameters and options for the field.

Option entries actually depend on the type of field, but some entries are common to all fields.

See AS.form.field documentation for common option keys and fields positioning.

Note:

Usually fields are added before invoking asForm.render(), but you can add them dynamically also later.
In this case the field is added at the end of the existing form (or tab, depending on its position).

asForm.destroy()

Removes the asForm from collection, removes its DOM nodes if any, returns the destroyed object.

A destroyed form can be added again to collection, rendered and used, with static method AS.form.addForm().

asForm.disableField( field, [flag] )

Disable both real and AS.form field.

See asForm.getField( field ) for details on field parameter.

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

asForm.enableField( field, [flag] )

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

See asForm.getField( field ) for details on field parameter.

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

asForm.errors( validateFlag )

Returns an array of AS.form.field objects that aren’t valid, an empty array if the whole form validates.

If validateFlag is true performs validation on each form field, and shows error warnings if any.

See also: asForm.valid(), asForm.validate()

asForm.fakeForm()

Returns the FORM DOM node of the fake form handling AS.form fields.

Returns undef if the AS.form object wasn’t rendered yet.

Notes:

• See also: asForm.realForm()
• The real form DOM node is provided with method formNode.asForm() that returns the asForm object associated.

asForm.fieldByName( fieldName )

Returns the AS.form.field object named fieldName defined in the AS.form object, if any, or false otherwise.

asForm.fieldValue( field, [default] )

An alternative to asForm.getField(field).getValue()

This is the way to retrieve the value associated to a field regardless of the fact that the field is or isn’t a control field.

Accepts one or two parameters:

1. field is a string (field name) or an asField object
2. default is the value to be returned if the field is empty, null, non-existing, disabled, zero or false. Defaults to undefined

Returns the javascript object representing the value (String, Number, Boolean, Array, Object or undefined).

asForm.getField( field )

Returns the AS.form.field object identified by field, if any, or false otherwise.

field can be:

1. A string: the field name
2. A number: the 0-based index in fields array
3. An object: an instance of AS.form.field

asForm.getJS( [stringsFlag] )

Returns a Javascript object with form values.

Disabled fields are not included.

If stringsFlag evaluates to true all values are strings, otherwise it’s checked if they can return as integer or float.

asForm.getJSON( [stringsFlag] )

Returns the JSON string of a Javascript object with form values.

Disabled fields are not included.

If stringsFlag evaluates to true all values are strings, otherwise it’s checked if they can return as integer or float.

asForm.getTheme()

Returns current asForm theme.

asForm.hide()

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

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

asForm.hideWarnings()

Hides every asField warning message, if any.

Invoked with false parameter is the same as asForm.showWarnings()

asForm.onReady( function )

Plugins aren loaded dynamically, possibly they're not immediately available and must be loaded.

WE’ve to defer the form object manipulation to a time when everything is loaded, e.g.: (new AS.form( options )).onReady( myFunction )

myFunction will receive as first parameter the reference to the created form, and you can use it:

function myFunction( theForm ) {
    theForm.addField( 'integer', { min: 0 } );
    theForm.render( document.getElementById('foo') );
}

asForm.parse( valuesObject )

Loads in a asForm object (rendered or not) field values – e.g.: values previously saved with asForm.getJS(), for edit.

If the asForm object wasn’t saved yet, asForm.parse() must be used after every asForm.addField().

• The new values become the reference values for the form, e.g.: a reset button will revert the form to such values.
• Every field hidden after form creation will revert to its original visibility.
• Every field mentioned in values object and disabled will be enabled.
• Every field not mentioned in values object and disabled after form creation will revert to its original enabled status.

Notes:

• Using AS.form.createForm() the values object to be parsed at form creation time is in the values property.

asForm.realField( field )

Returns the INPUT DOM node of the real (hidden) field associated to the AS.form.

Returns false if the AS.form object wasn’t rendered yet, or if the field doesn’t exist.

See asForm.getField( field ) for details on field parameter.

asForm.realForm()

Returns the FORM DOM node of the real (hidden) form associated to the AS.form.

Returns undef if the AS.form object wasn’t rendered yet.

Notes:

• See also: asForm.fakeForm()
• The real form DOM node is provided with method formNode.asForm() that returns the asForm object associated.

asForm.render( targetNode )

Appends the real form and the asForm to the node specified.

targetNode can be a DOM node (object) or a String (the ID of a DOM node).

asForm.reset()

Reset all fields to their initial value — or to the values set with asForm.parse().

asForm.rmField( field )

Removes the field field from the AS.form object, returns the removed field or false if error.

In case the AS.form object was rendered removes also the AS.form.field created and the real field associated.

See asForm.getField( field ) for details on field parameter.

asForm.scrollTo( field )

Scroll view to field field if defined in the AS.form object.

See asForm.getField( field ) for details on field parameter.

asForm.serialize( [fullFlag] )

Returns the string of the URI-encoded value of the form, ready for both GET QUERY_STRING and POST body content.

When the fullFlag is unset or false structured fields (objects, values) are reported with literal *JSON*.

When the fullFlag is true structured fields (objects, values) are valued with their encoded JSON representation.
In addition a _json_ parameter is added, reporting the comma separated list of the JSON-encoded fields.

asForm.setTheme( [theme] )

Change color theme for the form. If missing theme defaults to 'transparent'

Transparent is the default theme, black on transparent

as-form-basic provides also themes:

• Light (light) - black on light grey
• Cyan (cyan) - black on light cyan
• Black (black) - light grey on very dark grey

In brackets the class names used in the CSS file.

In case a non-matching theme name is used the class doesn’t exist, exactly like transparent: it’s the default because its rules are missing, and the default rules are used.

asForm.setValue( field, value, [skipValidation] )

Set value of field field (if defined in the AS.form object) to v, returns the field object or false.

1. See asForm.getField( field ) for details on field parameter. Can be a string (field name).
2. value if missing defaults to empty string.
3. skipValidation if true prevents field from validation process for this value.

Note

skipValidation can be false, true or missing (undefined).

In case it’s missing (undefined) this method will act at high-level rather than low-level.

This means that complex fields (e.g.: checklist, slider, etc.) will update both the value and the front-end fake form. In this case the field will be automatically validated.

asForm.show()

Makes AS.form visible.

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

asForm.showWarnings()

Shows every asField warning message, if any.

Invoked with false parameter is the same as asForm.hideWarnings()

asForm.valid()

Returns true if all fields are valid, false otherwise.

See also: asForm.validate(), asForm.errors()

asForm.validate()

Performs validation on each form field, and shows error warnings if any.

Returns true if all fields are valid, false otherwise.

See also: asForm.valid(), asForm.errors()

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

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