Form Component

with Twitter Bootstrap classes

a:form;

• Attributes

• API

• Signals

• Slots

• Components

  Input Elements

  • Input
  • Checkbox
  • Radio
  • Select
  • Text
  • Input
  • Array
  • Image
  • Template

  Ui

  • Progress
  • Notification

Attributes

• action Default is the current location. Endpoint to submit the form data to.

  Supports also dynamic entity key definition, e.g.:

  a:form action='/user/:userId';

  Now, when the model has the userId property, then the proper endpoint url is generated and the "edit" method is used. Otherwise the model is submited to the /user endpoint with the POST method.

• method Default is POST. Http Method.

• method-edit Default is PUT.

• get (String or just a flag). If specified, the component will load the model from the endpoint with the GET http method. When get is just a flag, then the action value is used. Supports dynamic entity key definition.

• content-type Default is application/json. Accepts also: multipart/form-data

• form-type Default is ''. Accepts also horizontal, inline. Refer to the Bootstrap Forms

• offset. Default is 0. When the form type is horizontal this attribute defines the col size for labels.

• redirect. Default is empty. When form successfully submits the data it will redict the page to the specified url.

• model-detached (Default is false) :muscle:

  The component creates its own model scope and set the to edit model to the entity property.

  This flag defines if the model should be shallow-copied before setting to the entity property

• in-memory (Default is false)

  Only signals are emitted without uploading to the endpoint

Mask interpolation are also supported.

// load the User model and display the form for it
a:form action='/user/~[userId]' method='PUT' get form-type=horizontal offset=4;

The example is similar to the dynamic entity key. But here we predefine the endpoint to be editable only.

Api

• validate():string Validate the model, and also all inner custom components (if any)

  To validate the custom components they must implement IValidation interface:

  IValidation {
  	// return error description or Error instance when validation fails
  	validate():string|Error
  }

• submit() Collects form data from the model and inner custom components

  To get custom components data, implement IFormBuilder interface:

  IFormBuilder {
  	// return json object, which is then merged with other data
  	toJson():object
  }

  Per default a:form sends json data. But if multipart/form-data is set for the content-type, then Json is tranformed to FormData instance. So you can upload also images and other binaries.

• setEntity(obj) Set the new model and refresh the component

• getEntity() Get current components model

• loadEntity(url) Loads the model from remote and apply it to the form. This function is automaticaly called on render start, when get attribute is defined.

• uploadEntity Perform POST/PATCH/PUT action according to form attributes. This function is called on submit signal.

• notify(type, message) Notifies about any status changes

Signals

a:form componenent emits signals to children on various states

• formActivity(type, ...args)

  Types:

  • start
  • progress: plus arguments 'load|upload', percent
  • end: variations ('end', 'upload', json), ('end', 'load', json)
  • complete: plus arguments json. When not in-memory flag is used then is equivalent to ('end', 'upload', json)
  • error: plus arguments Error
  • formGet: plus arguments Object (server response)
  • formPost: plus arguments Object (server response)
  • formPut: plus arguments Object (server response)
  • formPatch: plus arguments Object (server response)
  • formDelete: plus arguments Object (server response)

• formNotification(notification: Object<type, message>

Slots

• submit Submit entity
• delete Remove entity

Components

a:form defines some nested components. Each component is placed in a template: ItemLayout

Input Elements

All editors have dualbind component, sothat they are bound to the model with a two-way data model binding type.

Input

Attributes:

• property (required): Value in a model to edit
• type (optional): HtmlInput type value: 'string/number/email/etc'
• placeholder (optional): HtmlInput placeholder
• class (optional): Css class names

a:form {
	Input property='some.foo';
}

Placeholders:

• @label (optional) Defines nodes for the label in a .form-group

  a:form {
  	Input property='some.foo' {
  		@label > b > 'I am label'
  	}
  }

Text

textarea

Attributes:

• property (required): Value in a model to edit
• placeholder (optional): HtmlInput placeholder
• rows (optional): HtmlTextArea rows attribute
• class (optional): Css class names

a:form {
	Text property='description';
}

Placeholders:

• @label (optional)

Checkbox

Attributes:

• property (required): Value in a model to edit
• text (required): Input's label text
• class (optional): Css class names

a:form {
	Checkbox property='baz' text='Should handle baz';
}

Placeholders:

• @label (optional) Defines nodes for the label in a .form-group

  a:form {
  	Checkbox property='baz' text='Should handle baz' {
  		@label > 'Lorem ipsum'
  	}
  }

Radio

Attributes:

• property (required): Value in a model to edit
• class (optional): Css class names

Placeholders:

• @Option (required) Defines each Option for the radio group

  a:form {
  	Radio property='letter' {
  		@Option value='a' {
  			// nodes
  			'Letter A'
  		}
  		@Option value='b' > 'Letter B'
  		@Option value='c' > 'Letter C'
  	}
  }

• @label (optional)

Select

Attributes:

• property (required): Value in a model to edit
• class (optional): Css class names

Placeholders:

• @Option (required) Defines each Option for the radio group

  a:form {
  	Select property='letter' {
  		@Option value='a' {
  			// nodes
  			'Letter A'
  		}
  		@Option value='b' > 'Letter B'
  		@Option value='c' > 'Letter C'
  	}
  }

• @label (optional)

Image

Attributes:

• property (required): Value in a model to edit

a:form {
	Image property='avatar';
}

Placeholders:

• @label (optional)

Array

Edit the arrays: edit items, add items, remove items.

• Example

Slots:

• arrayItemAdd
• arrayItemRemove

Attributes:

• property: Property of an array in a model to edit

Placeholders:

• @template is a template for each item
• @header is a template to be rendered before the list
• @footer is a template to be rendered after the list

Template

Wraps nested nodes in the ItemLayout.

Otherwise you can place any mask nodes inside the a:form component

Placeholders:

• @template (required)

  a:form {
  	Template > @template {
  		MyPicker > dualbind value='myvalue';
  	}
  }

Ui

a:form has some default components to provide error/success/progress notifications.

Notification

See the implementation at Notification.mask

How to override

mask.define('a:form', `
	let Notification {
		.my-status {
			h4 > '~[bind: $scope.notificationMsg ]'
		}
	}
`)

Progress

See the implementation at Progress.mask

Examples

• /examples

# install atma toolkit
npm install atma -g
# run examples static server
npm run examples

# navigate `http://localhost:5777/examples/index.html?input`

Test

npm test

:copyright: MIT - Atma.js Project