# Class: Form

## jala.Form(name, dataObj)

A class that renders forms, validates submitted form data and stores the data in a specified object.

## Constructor

#### new Form(name, dataObj)

Constructs a new Form instance

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | String | The name of the form
`dataObj` | Object | An optional object used to retrieve values to display in the form input fields contained in this Form instance.

Source:
  - jala/code/Form.js, line 59

##### Returns:

A newly created Form instance

### Classes

Component
Tracker

### Members

#### componentSkin :Skin

Contains the default component skin

##### Type:

- Skin

Source:
  - jala/code/Form.js, line 188

#### components :Object

Contains a map of component objects.

##### Type:

- Object

Source:
  - jala/code/Form.js, line 194

#### getter :function

The default getter function for this form. Unless a getter is specified for the component, this function is called to retrieve the original value of a field. When called, the scope is set to the data object and the name of the element is the sole argument.

##### Type:

- function

Source:
  - jala/code/Form.js, line 126
See:
  - jala.Form.Component.Input#getValue

#### name :String

Readonly reference to the name of the form

##### Type:

- String

Source:
  - jala/code/Form.js, line 92

#### setter :function

The default setter function for this form. Unless a getter is specified for the component, this function is called to store the a value of a field. When called, the scope is set to the data object and the name and value of the element are provided as arguments.

##### Type:

- function

Source:
  - jala/code/Form.js, line 148
See:
  - jala.Form.Component.Input#setValue

#### (static, readonly) CHECKOPTIONS :String

Constant used by require function to define that a select or radio component should validate only if the user input is contained in the list of options provided. Value: "checkoptions"

##### Type:

- String

Source:
  - jala/code/Form.js, line 353

#### (static, readonly) CONTENTTYPE :String

Constant used by require function to define that a file upload component should validate only if the file's content type is in the list of allowed content types provided. Value: "contenttype"

##### Type:

- String

Source:
  - jala/code/Form.js, line 363

#### (static, readonly) MAXHEIGHT :String

Constant used by require function to define that an image upload component should validate only if the image's height is less than the value provided. Value: "maxheight"

##### Type:

- String

Source:
  - jala/code/Form.js, line 393

#### (static, readonly) MAXLENGTH :String

Constant used by require function to define that a component should not validate if userinput exceeds a maximum length. Value: "maxlength"

##### Type:

- String

Source:
  - jala/code/Form.js, line 334

#### (static, readonly) MAXWIDTH :String

Constant used by require function to define that an image upload component should validate only if the image's width is less than the value provided. Value: "maxwidth"

##### Type:

- String

Source:
  - jala/code/Form.js, line 373

#### (static, readonly) MINHEIGHT :String

Constant used by require function to define that an image upload component should validate only if the image's height is more than the value provided. Value: "min-height"

##### Type:

- String

Source:
  - jala/code/Form.js, line 403

#### (static, readonly) MINLENGTH :String

Constant used by require function to define that a component should not validate if userinput is shorter than a given length. Value: "minlength"

##### Type:

- String

Source:
  - jala/code/Form.js, line 325

#### (static, readonly) MINWIDTH :String

Constant used by require function to define that an image upload component should validate only if the image's width is more than the value provided. Value: "minwidth"

##### Type:

- String

Source:
  - jala/code/Form.js, line 383

#### (static, readonly) REQUIRE :String

Constant used by require function to define that a component should validate only if the user did provide input. Value: "require"

##### Type:

- String

Source:
  - jala/code/Form.js, line 343

#### (static) html :helma.Html

The HTML renderer used by jala.Form

##### Type:

- helma.Html

Source:
  - jala/code/Form.js, line 316

#### (inner) className :String

Private field containing the CSS class name of this form instance.

##### Type:

- String

Source:
  - jala/code/Form.js, line 79

### Methods

#### addComponent(component)

Adds a component to this jala.Form instance

##### Parameters:

Name | Type | Description
--- | --- | ---
`component` | jala.Form.Component.Input |

Source:
  - jala/code/Form.js, line 210

#### class_macro()

Returns the class name of the form

Source:
  - jala/code/Form.js, line 753

##### Returns:

The class name of this Form instance

#### close_macro()

Writes the form closing tag to response

Source:
  - jala/code/Form.js, line 774

#### containsFileUpload()

Returns true if this instance of jala.Form contains at least one component doing a file upload.

Source:
  - jala/code/Form.js, line 223
See:
  - jala.Form.Component#containsFileUpload

#### countErrors()

If this instance of jala.Form holds a jala.Form.Tracker instance it returns the number of components that didn't validate.

Source:
  - jala/code/Form.js, line 290

##### Returns:

Number of components that didn't validate.

#### createDomId()

Creates a DOM identifier based on the arguments passed. The resulting Id will be prefixed with the name of the form. All arguments will be chained using camel casing.

Source:
  - jala/code/Form.js, line 649

##### Returns:

The DOM Id

#### getClassName()

Returns the class name set for this form instance.

Source:
  - jala/code/Form.js, line 237

##### Returns:

class name

#### getDataObject()

Returns the data object containing the values used for rendering the form.

Source:
  - jala/code/Form.js, line 112

##### Returns:

The data object of this jala.Form instance

#### getErrorMessage()

Returns the general error message printed above the form if any of the components didn't validate.

Source:
  - jala/code/Form.js, line 256

##### Returns:

error message

#### getTracker()

Returns the tracker object this form instance uses for collecting error messages and parsed values.

Source:
  - jala/code/Form.js, line 180

##### Returns:

tracker object

#### handle(reqData, destObj)

Parses form input, applies check functions and stores the values if the form does validate. Otherwise this method returns false without saving so that the form can be reprinted with error messages.

##### Parameters:

Name | Type | Description
--- | --- | ---
`reqData` | Object | input from form
`destObj` | Object | object whose values should be chanegd

Source:
  - jala/code/Form.js, line 710

##### Returns:

False if one of the checks failed, true if the element was saved correctly.

#### hasError()

Returns true if this instance of jala.Form holds a jala.Form.Tracker instance and at least one error has been set on this tracker.

Source:
  - jala/code/Form.js, line 276

##### Returns:

true if an error has been encountered.

#### id_macro()

Returns the id (equal to the name) of the form

Source:
  - jala/code/Form.js, line 733

##### Returns:

The id of this Form instance

#### listComponents()

Returns an array containing the components of this jala.Form instance.

Source:
  - jala/code/Form.js, line 202

##### Returns:

The components of this jala.Form instance.

#### name_macro()

Returns the name (equal to the id) of the form

Source:
  - jala/code/Form.js, line 743

##### Returns:

The name of this Form instance

#### open_macro()

Writes the form opening tag to response

Source:
  - jala/code/Form.js, line 766

#### render()

Renders this form including all components to response.

Source:
  - jala/code/Form.js, line 605

#### renderAsString()

renders the form as a string

Source:
  - jala/code/Form.js, line 636

##### Returns:

rendered form

#### render_macro()

Renders the whole form to response

Source:
  - jala/code/Form.js, line 723

#### save(tracker, destObj)

Sets the parsed values on an object. By default the internally stored tracker and data objects are used, but those may be overridden here.

##### Parameters:

Name | Type | Description
--- | --- | ---
`tracker` | jala.Form.Tracker | (optional) tracker object holding parsed data from form input.
`destObj` | Object | (optional) object whose values will be changed. By default the dataObj passed to the constructor or to setDataObject is used.

Source:
  - jala/code/Form.js, line 690

#### setClassName(newClassName)

Sets an extra classname for this form instance

##### Parameters:

Name | Type | Description
--- | --- | ---
`newClassName` | String | new classname

Source:
  - jala/code/Form.js, line 245

#### setDataObject(dataObj)

Sets the data object which is being edited by this form. This object is used to get the default values when first printing the form and - if no other object is provided - receives the changed values in save.

##### Parameters:

Name | Type | Description
--- | --- | ---
`dataObj` | Object | The object which is being edited by this form.

Source:
  - jala/code/Form.js, line 102
See:
  - #save

#### setErrorMessage(newErrorMessage)

Sets the general error message printed above the form if any of the components didn't validate.

##### Parameters:

Name | Type | Description
--- | --- | ---
`newErrorMessage` | String | error message

Source:
  - jala/code/Form.js, line 265

#### setTracker(newTracker)

Sets the tracker object this form instance uses for collecting error messages and parsed values.

##### Parameters:

Name | Type | Description
--- | --- | ---
`newTracker` | jala.Form.Tracker |

Source:
  - jala/code/Form.js, line 167

#### validate(reqData)

Validates user input from a submitted form by calling each component's validate method.

##### Parameters:

Name | Type | Description
--- | --- | ---
`reqData` | Object | Optional submitted form data. If not specified req.data is used.

Source:
  - jala/code/Form.js, line 670

##### Returns:

tracker object with error fields set.

#### (static) create(config)

Parses a plain javascript object tree and configures a new jala.Form instance according to the properties. Propertynames are matched with constants and setter-functions, the property "type" is used to create new component objects.

##### Parameters:

Name | Type | Description
--- | --- | ---
`config` | Object | object tree containing config

Source:
  - jala/code/Form.js, line 431

##### Returns:

A newly created jala.Form instance based on the config specified

#### (static) extend(subClass, superClass)

Utility to set up the prototype, constructor, superclass and superconstructor properties to support an inheritance strategy that can chain constructors and methods.

##### Parameters:

Name | Type | Description
--- | --- | ---
`subClass` | function | the object which inherits superClass' functions
`superClass` | function | the object to inherit

Source:
  - jala/code/Form.js, line 411

#### (static) isEmail(name, value, reqData, formObj)

Static validator function to test values for being a valid email address.

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | String | name of the property being validated.
`value` | String | value in form input
`reqData` | Object | the whole request-data-object, in case properties depend on each other
`formObj` | jala.Form | instance of jala.Form

Source:
  - jala/code/Form.js, line 555

##### Returns:

Error message or null

#### (static) isUrl(name, value, reqData, formObj)

Static validator function to test values for being a valid url.

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | String | name of the property being validated.
`value` | String | value in form input
`reqData` | Object | the whole request-data-object, in case properties depend on each other
`formObj` | jala.Form | instance of jala.Form

Source:
  - jala/code/Form.js, line 572

##### Returns:

Error message or null

#### (static) propertyGetter(name)

static default getter function used to return a field from the data object.

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | String | Name of the property.

Source:
  - jala/code/Form.js, line 2433

#### (static) propertySetter(name, value)

static default setter function used to change a field of the data object.

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | String | Name of the property.
`value` | Object | New value of the property.

Source:
  - jala/code/Form.js, line 2443