altersoftware.IT
altersoftware.IT

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

Library index

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

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:

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:

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().

Notes:

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:

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:

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()