Jala 1.3

## Class jala.Form

    Object
       |
       +--jala.Form

class jala.Form

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

Nested Class Summary
`<static class>` | `jala.Form.Component`
`<static class>` | `jala.Form.Tracker`

Field Summary
`Skin` | `componentSkin` Contains the default component skin
`String` | `name` Readonly reference to the name of the form
`<static> <final> String` | `CHECKOPTIONS` 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.
`<static> <final> String` | `CONTENTTYPE` 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.
`<static> helma.Html` | `html` The HTML renderer used by jala.Form
`<static> <final> String` | `MAXHEIGHT` 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.
`<static> <final> String` | `MAXLENGTH` Constant used by require function to define that a component should not validate if userinput exceeds a maximum length.
`<static> <final> String` | `MAXWIDTH` 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.
`<static> <final> String` | `MINHEIGHT` 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.
`<static> <final> String` | `MINLENGTH` Constant used by require function to define that a component should not validate if userinput is shorter than a given length.
`<static> <final> String` | `MINWIDTH` 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.
`<static> <final> String` | `REQUIRE` Constant used by require function to define that a component should validate only if the user did provide input.

Constructor Summary
`jala.Form (<String> name, <Object> dataObj)` Constructs a new Form instance

Method Summary
`void` | `addComponent(<jala.Form.Component.Input> component)` Adds a component to this jala.Form instance
`String` | `class_macro()` Returns the class name of the form
`void` | `close_macro()` Writes the form closing tag to response
`Boolean` | `containsFileUpload()` Returns true if this instance of jala.Form contains at least one component doing a file upload.
`Number` | `countErrors()` If this instance of jala.Form holds a jala.Form.Tracker instance it returns the number of components that didn't validate.
`String` | `createDomId()` Creates a DOM identifier based on the arguments passed.
`String` | `getClassName()` Returns the class name set for this form instance.
`Object` | `getDataObject()` Returns the data object containing the values used for rendering the form.
`String` | `getErrorMessage()` Returns the general error message printed above the form if any of the components didn't validate.
`jala.Form.Tracker` | `getTracker()` Returns the tracker object this form instance uses for collecting error messages and parsed values.
`Boolean` | `handle(<Object> reqData, <Object> destObj)` Parses form input, applies check functions and stores the values if the form does validate.
`Boolean` | `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.
`String` | `id_macro()` Returns the id (equal to the name) of the form
`Array` | `listComponents()` Returns an array containing the components of this jala.Form instance.
`String` | `name_macro()` Returns the name (equal to the id) of the form
`void` | `open_macro()` Writes the form opening tag to response
`void` | `render()` Renders this form including all components to response.
`void` | `render_macro()` Renders the whole form to response
`String` | `renderAsString(param)` renders the form as a string
`void` | `save(<jala.Form.Tracker> tracker, <Object> destObj)` Sets the parsed values on an object.
`void` | `setClassName(<String> newClassName)` Sets an extra classname for this form instance
`void` | `setDataObject(newDataObj)` Sets the data object which is being edited by this form.
`void` | `setErrorMessage(<String> newErrorMessage)` Sets the general error message printed above the form if any of the components didn't validate.
`void` | `setTracker(<jala.Form.Tracker> newTracker)` Sets the tracker object this form instance uses for collecting error messages and parsed values.
`jala.Form.Tracker` | `validate(<Object> reqData)` Validates user input from a submitted form by calling each component's validate method.
`<static> jala.Form` | `create(<Object> config, dataObj)` Parses a plain javascript object tree and configures a new jala.Form instance according to the properties.
`<static> void` | `extend(<Function> subClass, <Function> superClass)` Utility to set up the prototype, constructor, superclass and superconstructor properties to support an inheritance strategy that can chain constructors and methods.
`<static> String` | `isEmail(<String> name, <String> value, <Object> reqData, <jala.Form> formObj)` Static validator function to test values for being a valid email address.
`<static> String` | `isUrl(<String> name, <String> value, <Object> reqData, <jala.Form> formObj)` Static validator function to test values for being a valid url.
`<static> Object` | `propertyGetter(<String> name, value)` static default getter function used to return a field from the data object.
`<static> void` | `propertySetter(<String> name, <Object> value)` static default setter function used to change a field of the data object.

Field Detail

### componentSkin

    Skin componentSkin

Contains the default component skin

### name

    String name

Readonly reference to the name of the form

### CHECKOPTIONS

    <static> <final> String CHECKOPTIONS

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"

See Also:
  Constant Field Values

### CONTENTTYPE

    <static> <final> String CONTENTTYPE

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"

See Also:
  Constant Field Values

### html

    <static> helma.Html html

The HTML renderer used by jala.Form

### MAXHEIGHT

    <static> <final> String MAXHEIGHT

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"

See Also:
  Constant Field Values

### MAXLENGTH

    <static> <final> String MAXLENGTH

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

See Also:
  Constant Field Values

### MAXWIDTH

    <static> <final> String MAXWIDTH

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"

See Also:
  Constant Field Values

### MINHEIGHT

    <static> <final> String MINHEIGHT

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"

See Also:
  Constant Field Values

### MINLENGTH

    <static> <final> String MINLENGTH

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

See Also:
  Constant Field Values

### MINWIDTH

    <static> <final> String MINWIDTH

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"

See Also:
  Constant Field Values

### REQUIRE

    <static> <final> String REQUIRE

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

See Also:
  Constant Field Values

Constructor Detail

### jala.Form

    jala.Form(<String> name, <Object> dataObj)

Constructs a new Form instance

Parameters:

`name` - The name of the form

`dataObj` - An optional object used to retrieve values to display in the form input fields contained in this Form instance.

Returns:

A newly created Form instance

Method Detail

### addComponent

    void addComponent(<jala.Form.Component.Input> component)

Adds a component to this jala.Form instance

Parameters:

`component` -

### class_macro

    String class_macro()

Returns the class name of the form

Returns:

The class name of this Form instance

### close_macro

    void close_macro()

Writes the form closing tag to response

### containsFileUpload

    Boolean containsFileUpload()

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

See:

- jala.Form.Component#containsFileUpload

### countErrors

    Number countErrors()

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

Returns:

Number of components that didn't validate.

### createDomId

    String 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.

Returns:

The DOM Id

### getClassName

    String getClassName()

Returns the class name set for this form instance.

Returns:

class name

### getDataObject

    Object getDataObject()

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

Returns:

The data object of this jala.Form instance

### getErrorMessage

    String getErrorMessage()

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

Returns:

error message

### getTracker

    jala.Form.Tracker getTracker()

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

Returns:

tracker object

### handle

    Boolean handle(<Object> reqData, <Object> 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:

`reqData` - input from form

`destObj` - object whose values should be chanegd

Returns:

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

### hasError

    Boolean 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.

Returns:

true if an error has been encountered.

### id_macro

    String id_macro()

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

Returns:

The id of this Form instance

### listComponents

    Array listComponents()

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

Returns:

The components of this jala.Form instance.

### name_macro

    String name_macro()

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

Returns:

The name of this Form instance

### open_macro

    void open_macro()

Writes the form opening tag to response

### render

    void render()

Renders this form including all components to response.

### render_macro

    void render_macro()

Renders the whole form to response

### renderAsString

    String renderAsString(param)

renders the form as a string

Returns:

rendered form

### save

    void save(<jala.Form.Tracker> tracker, <Object> 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:

`tracker` - (optional) tracker object holding parsed data from form input.

`destObj` - (optional) object whose values will be changed. By default the dataObj passed to the constructor or to setDataObject is used.

### setClassName

    void setClassName(<String> newClassName)

Sets an extra classname for this form instance

Parameters:

`newClassName` - new classname

### setDataObject

    void setDataObject(newDataObj)

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:

`dataObj` - The object which is being edited by this form.

See:

- save()

### setErrorMessage

    void setErrorMessage(<String> newErrorMessage)

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

Parameters:

`newErrorMessage` - error message

### setTracker

    void setTracker(<jala.Form.Tracker> newTracker)

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

Parameters:

`newTracker` -

### validate

    jala.Form.Tracker validate(<Object> reqData)

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

Parameters:

`reqData` - Optional submitted form data. If not specified req.data is used.

Returns:

tracker object with error fields set.

### create

    <static> jala.Form create(<Object> config, dataObj)

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:

`config` - object tree containing config

Returns:

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

### extend

    <static> void extend(<Function> subClass, <Function> superClass)

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

Parameters:

`subClass` - the object which inherits superClass' functions

`superClass` - the object to inherit

### isEmail

    <static> String isEmail(<String> name, <String> value, <Object> reqData, <jala.Form> formObj)

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

Parameters:

`name` - name of the property being validated.

`value` - value in form input

`reqData` - the whole request-data-object, in case properties depend on each other

`formObj` - instance of jala.Form

Returns:

Error message or null

### isUrl

    <static> String isUrl(<String> name, <String> value, <Object> reqData, <jala.Form> formObj)

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

Parameters:

`name` - name of the property being validated.

`value` - value in form input

`reqData` - the whole request-data-object, in case properties depend on each other

`formObj` - instance of jala.Form

Returns:

Error message or null

### propertyGetter

    <static> Object propertyGetter(<String> name, value)

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

Parameters:

`name` - Name of the property.

### propertySetter

    <static> void propertySetter(<String> name, <Object> value)

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

Parameters:

`name` - Name of the property.

`value` - New value of the property.

Jala 1.3

Documentation generated by JSDoc on Tue Jan 8 15:45:31 2008