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

Library index

Plugin: “as-form-basic”

Developed and maintained by balestra

Licensed under Creative Commons Attribution 4.0 License for free personal/professional/commercial use, with attribution.

Includes some glyphicons, licensed to Marco Balestra.

Version 1.4, released on 2020-12-01

Provides

Some basic data types are provided with as-form-basic.js:

as-form-basic.js provides also a few basic themes:

Load plugin

Plugin URI: https://cdn.altersoftware.org/js-as-form/plugin/as-form-basic.js

Plugin name: basic

Field types

bool

asForm.addField(fieldname,'bool', {options…} )

Generates a single checkbox, returns true if checked or nothing otherwise. Common option keys can be used.

In addition:

Additional methods:

See also: truefalse

Notes:

  1. value, if any, is ignored: value will be true.
  2. An unchecked checkbox field isn’t part of fields sent with submit, nor included in asForm.getJS() - its related asField.realField() is actually disabled.
  3. When unchecked asField.getValue() always returns undefined.
  4. A mandatory checkbox won’t validate if unchecked.

buttons

asForm.addField(fieldname,'buttons', {options…} )

Generates a buttons area (row), as a control field (not reported in form values, even if name is still mandatory and must be unique in the form).

Common option keys can be used (if they make sense, e.g.: hidden).

In addition:

button description

A button description is a javascript object with the following keys:

E.g.:

myForm.addField([
    'myButtons',
    'buttons',
    {
        list:[
            {label:'Exit',onclick:function(){ myForm.destroy(); } },
            {btype:'reset'},
            {btype:'submit'}
        ]
    }
]);

checkbox

asForm.addField(fieldname,'checkbox', {options…} )

Single checkbox. Common option keys can be used.

In addition:

Additional methods:

Notes:

  1. An unchecked checkbox field isn’t part of fields sent with submit, nor included in asForm.getJS() - its related asField.realField() is actually disabled.
  2. When unchecked asField.getValue() always returns undefined.
  3. A mandatory checkbox won’t validate if unchecked, or if its value is empty.

checklist

asForm.addField(fieldname,'checklist', {options…} )

An advanced field (or set of fields) where radio buttons and checkboxes can be used, also mixed and hierarchical.

Common option keys can be used, in addition:

list as array

The array can contain strings or objects.

A single string Foo becomes {label:"Foo",value:"Foo"}, with name and ctype inherited by the parent.

An object can have the following keys:

list as object

ctype and name are inherited by parent node.

It’s possible to override this behavior for a list of nodes by using list as an object, with keys:

In this case ctype and/or name become the parent values for list array of controls.

Notes:

  1. When a radio control is selected all other controls with the same name (specified or inherited) are deselected.
  2. When a real field is empty it’s disabled.
  3. When a real field has more than one value its value attribute is the JSON representation of the array of values.
    In this case the asForm.getJS() method parses the value and returns the array.
  4. When a list is part of a control its children nodes are shown only when the control is selected.
  5. When a named (or inherited) name is mandatory this applies also to all other controls under the same name (declared or onherited).
  6. With the exception of root options node, name in list items can report multiple names comma separated. In this case the value of the controls when selected will span on all the named fields.
  7. When mandatory is true for multiple names it applies to every named field in the list.

freehtml

asForm.addField(fieldname,'freehtml', {value: …} )

Common option keys can be used, but validation options are ignored (all but override).

Notes:

  1. Field name may look useless, but it’s required by addField() syntax.
    You can use it later on, e.g. to retrieve the field and hide it.
    In alternative use an empty string, a random name will be generated.
  2. getValue() and setValue() methods read and write HTML content.
  3. iscontrol, nolabel and nowarning options are automatically set to true.
  4. Validation is always true, neither real field nor warning or label are generated.
  5. Don’t forget to provide value options attribute, valued with a string or a DOM node. If a DOM node is used its innerHTML is copied, the node itself isn’t touched.
  6. HTML content spans on the whole available width.

hidden

asForm.addField(fieldname,'hidden', {options…} )

Common option keys can be used. Dont’t forget that in case of validation failure no warning is shown.

Notes:

  1. When using hidden fields be careful with mandatory, calc, expr etc.: if validation fails no warning is on display, but the form cannot submit anyway.

hr

asForm.addField(fieldname,'hr')

Adds an horizontal ruler that looks fine on both mobile and desktop.

Option keys make no sense, and validation options are ignored (all but override).

Notes:

  1. The ruler spans on the whole available width.
  2. Field name may look useless, but it’s required by addField() syntax.
    You can use it later on, e.g. to retrieve the field and hide it.
    In alternative use an empty string, a random name will be generated.
  3. Initial value is automatically set to <hr />.
  4. getValue() and setValue() methods read and write HTML content.
  5. iscontrol, nolabel and nowarning options are automatically set to true.
  6. Validation is always true, neither real field nor warning or label are generated.

integer

asForm.addField(fieldname,'integer', {options…} )

Common option keys can be used.

In addition more optional keys:

Additional methods:

select

asForm.addField(fieldname,'select', {options…} )

Common option keys can be used.

In addition:

e.g.:

f.addField(
    'hair',
    'select',
    {
        label: 'Hair',
        options: [
            {label:AS.label('selectChooseOne'),value:''},
            {label:'None',value:'-'},
            {label:'Dark:', options:['Black','Brown',{label:'Gray',value:'DarkGray'}]},
            {label:'Light:',options:['Red','Blonde','Gray','White']},
            'Other'
        ]
    }
);

About options.options

  1. options.options is an array of options or optgroups
  2. An option can be a string, or an object {label: '…', value: … }
  3. An option is initially selected if its value is equal to options.value or options.default
  4. An optgroup is an object like { label: '…', options: [ optionsOrOptgroups ] }
  5. The label selectChooseOne is pre-defined in the core labels loaded by AS.form

Additional methods:

subform

asForm.addField(fieldname,'subform', {options…} )

This field is the key to define structured data: creates a new form that harvest details, and returns to the field a JSON representation of harvested data.

Recursion is allowed-

Common option keys can be used.

In addition more keys:

subform

Subform is a javascript object with 3 properties:

E.g:

myForm.addField(['name','subform',{ label:'Full Name', mandatory: true, subform: {
    subtype: 'object',
    preview: ['firstName','familyName'],
    values: [
        ['firstName','text',{label:'First Name',normalize:true,mandatory:true}],
        ['middleName','text',{label:'First Name',normalize:true,skipempty:true}],
        ['lastName','text',{label:'First Name',normalize:true,mandatory:true}],
    ]
}}]);

subforms

When subform is a string, its value must the the property of a subforms object that could be declared both in the field options or in the form options.

E.g:

myForm.addField(['name','subform',{ label:'Full Name', mandatory: true, subform'fullName', subforms: {
    fullName: {
        subtype: 'object',
        preview: ['firstName','familyName'],
        values: [
            ['firstName','text',{label:'First Name',normalize:true,mandatory:true}],
            ['middleName','text',{label:'First Name',normalize:true,skipempty:true}],
            ['lastName','text',{label:'First Name',normalize:true,mandatory:true}],
        ]
    }
}}]);

subparts

Both subform and subforms items can refer to shared objects defined in subparts, and subparts could be defined at field options level or at form option level (so that more fields can access it).

myForm.addField(['relatives','subform',{
    subform:'relatives',
    label:'Relatives',
    subparts: {
        title: ['title','select',{label:'Title',options:['Mr','Mrs']}],
        firstName: ['firstName','text',{label:'First Name',normalize:true,mandatory:true,focus:true}],
        middleName: ['middleName','text',{label:'Middle Name',normalize:true,skipempty:true}],
        familyName: ['familyName','text',{label:'Family Name',normalize:true,mandatory:true}],
    },
    subforms : {
        fullname: {
            subtype: 'object',
            preview: ['firstName','familyName'],
            values: [
                {subpart:'title'},
                {subpart:'firstName'},
                {subpart:'middleName'},
                {subpart:'familyName'}
            ]
        },
        relatives: {
            subtype: 'array',
            preview: ['firstName','familyName'],
            values: [
                ['name','subform',{subform:'fullname',label:'Full name',mandatory:true}],
                ['children','subform',{label:'Children',subform:'relatives',skipempty:true}]
            ]
        },
    }
}]);

This example illustrates also recursive use of subform.

Of course subparts becomes more useful if it’s (and optionally subforms is) defined at form options level.

An example is available here.

text

asForm.addField(fieldname,'text', {options…} )

Common option keys can be used.

In addition more optional keys:

Additional methods:

truefalse

asForm.addField(fieldname,'truefalse', {options…} )

Generates a single checkbox, returns true if checked or false otherwise. Common option keys can be used.

In addition:

Additional methods:

See also: bool

Notes:

  1. value, if any, is ignored: value will be true or false.
  2. Also unchecked truefalse checkboxes are part of fields sent with submit, valued false.
  3. A mandatory checkbox won’t validate if unchecked.

Version history


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

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