This class can be used to render forms and to validate
and store user submits. Further types of form components can be added
by subclassing jala.Form.Component.Input.
Constructs a new Form instance
parameters
String | name | The name of the form |
Object | dataObj | An optional object used to retrieve values to display in the form input fields contained in this Form instance. |
methods
- setDataObject(dataObj)
- setTracker(newTracker)
- addComponent(component)
- setClassName(newClassName)
- setErrorMessage(newErrorMessage)
- hasError()
- render()
- renderAsString(param)
- validate(reqData)
- save(tracker, destObj)
- handle(reqData, destObj)
- id_macro()
properties
- String name
- Skin componentSkin
- Object components
The abstract base class for all components.
parameters
name |
methods
- getType()
- setClassName(newClassName)
- createDomId(idPart)
- render()
- validate(tracker)
- save(destObj, val)
Constructs a new Fieldset instance
parameters
String | name | The name of the fieldset |
methods
- addComponent(component)
- setLegend(newLegend)
- render()
- validate(tracker)
- save(tracker, destObj)
properties
Subclass of jala.Form.Component that allows rendering a skin
within a form.
parameters
String | name | The name of the component, used as the name of the skin |
methods
- setHandler(newHandler)
- render()
Creates a new input component instance.
parameters
String | name | Name of the component, used as name of the html control. |
methods
- require(key, val, msg)
- getRequirement(key)
- setMessage(key, msg)
- getMessage(key, defaultMsg, args)
- getLabel()
- setLabel(newLabel)
- getHelp()
- setHelp(newHelp)
- validate(tracker)
- save(tracker, destObj)
- getValue()
- setValue(destObj, value)
- render()
- id_macro()
- checkLength(reqData)
- checkRequirements(reqData)
- parseValue(reqData)
- renderControls(attr, value, reqData)
Constructs a newly created Password component instance
parameters
String | name | Name of the component, used as name of the html controls. |
methods
- renderControls(attr, value, reqData)
Constructs a newly created Hidden component instance
parameters
String | name | Name of the component, used as name of the html controls. |
methods
- render()
- renderControls(attr, value, reqData)
Constructs a new Textarea component.
parameters
String | name | Name of the component, used as name of the html controls. |
methods
- getRows()
- setRows(newRows)
- getCols()
- setCols(newCols)
- renderControls(attr, value, reqData)
Constructs a new Date component instance
parameters
String | name | Name of the component, used as name of the html controls. |
methods
- setDateFormat(newDateFormat)
- renderControls(attr, value, reqData)
- checkRequirements(reqData)
- parseValue(reqData)
Constructs a new Select component instance
parameters
String | name | Name of the component, used as name of the html controls. |
methods
- setOptions(newOptions)
- setFirstOption(newFirstOption)
- renderControls(attr, value, reqData)
- checkRequirements(reqData)
- checkOptions(reqData)
Creates a new Radio component instance
parameters
String | name | Name of the component, used as name of the html controls. |
methods
- renderControls(attr, value)
- checkRequirements(reqData)
Creates a new Checkbox component instance
parameters
String | name | Name of the component, used as name of the html controls. |
methods
- renderControls(attr, value)
- parseValue(reqData)
- checkRequirements(reqData)
Creates a new File component instance
parameters
String | name | Name of the component, used as name of the html controls. |
methods
- renderControls(attr, value, reqData)
- checkRequirements(reqData, tracker)
Creates a new Image component instance
parameters
String | name | Name of the component, used as name of the html controls. |
methods
- checkRequirements(reqData)
Creates a new Button component instance
parameters
String | name | Name of the component, used as name of the html controls. |
methods
- getValue()
- setValue(newValue)
- render(attr, value, reqData)
- renderControls(attr, value)
Creates a new Submit component instance
parameters
String | name | Name of the component, used as name of the html controls. |
methods
- renderControls(attr, value)
A generic container for error-messages and values
parameters
reqData |
methods
- hasError()
properties
- Object reqData
- Object values
- Object errors
Readonly reference to the name of the form
Contains the default component skin
Contains a map of component objects.
The HTML renderer used by jala.Form
Constant used by require function to define that a component
should not validate if userinput is shorter than a given length.
Value: "minlength"
Constant used by require function to define that a component
should not validate if userinput exceeds a maximum length.
Value: "maxlength"
Constant used by require function to define that a component
should validate only if the user did provide input.
Value: "require"
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"
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"
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"
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"
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"
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"
Contains a map of all component objects of this fieldset
A map containing input from request data
A map containing parsed values (only for those fields that didn't
fail during checkRequirements method).
A map containing error messages
Methods
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
Object | dataObj | The object which is being edited by this form. |
see
Returns the data object containing the values used
for rendering the form.
returns
The data object of this jala.Form instance |
Sets the tracker object this form instance uses for collecting
error messages and parsed values.
parameters
jala.Form.Tracker | newTracker |
Returns the tracker object this form instance uses for collecting
error messages and parsed values.
returns
tracker object |
Returns an array containing the components
of this jala.Form instance.
returns
The components of this jala.Form instance. |
Adds a component to this jala.Form instance
parameters
jala.Form.Component.Input | component |
Returns true if this instance of jala.Form contains at least
one component doing a file upload.
see
Sets an extra classname for this form instance
parameters
String | newClassName | new classname |
Returns the general error message printed above the form
if any of the components didn't validate.
returns
error message |
Sets the general error message printed above the form if any
of the components didn't validate.
parameters
String | newErrorMessage | error message |
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. |
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. |
Utility to set up the prototype, constructor, superclass and superconstructor
properties to support an inheritance strategy that can chain constructors and methods.
parameters
Function | subClass | the object which inherits superClass' functions |
Function | superClass | the object to inherit |
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
Object | config | object tree containing config |
returns
A newly created jala.Form instance based on the config specified |
Static validator function to test values for being a valid email address.
parameters
String | name | name of the property being validated. |
String | value | value in form input |
Object | reqData | the whole request-data-object, in case properties depend on each other |
jala.Form | formObj | instance of jala.Form |
returns
Error message or null |
Static validator function to test values for being a valid url.
parameters
String | name | name of the property being validated. |
String | value | value in form input |
Object | reqData | the whole request-data-object, in case properties depend on each other |
jala.Form | formObj | instance of jala.Form |
returns
Error message or null |
Renders this form including all components to response.
renders the form as a string
parameters
param |
returns
rendered form |
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 |
Validates user input from a submitted form by calling each
component's validate method.
parameters
Object | reqData | Optional submitted form data. If not specified req.data is used. |
returns
tracker object with error fields set. |
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
jala.Form.Tracker | tracker | (optional) tracker object holding parsed data from form input. |
Object | destObj | (optional) object whose values will be changed. By default the dataObj passed to the constructor or to setDataObject is used. |
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
Object | reqData | input from form |
Object | destObj | object whose values should be chanegd |
returns
False if one of the checks failed, true if the element was saved correctly. |
Renders the whole form to response
Returns the id (equal to the name) of the form
returns
The id of this Form instance |
Returns the name (equal to the id) of the form
returns
The name of this Form instance |
Returns the class name of the form
returns
The class name of this Form instance |
Writes the form opening tag to response
Writes the form closing tag to response
Returns the type of component. This is the lowercase'd name of the
constructor function.
Returns the class name set for this component.
returns
class name |
Sets an extra classname for this component
parameters
String | newClassName | new classname |
Function defining wheter a component contains a file upload or not.
This value is used to render a form tag with the attribute
enctype=multipart/form-data.
Subclasses of jala.Form.Component that use a file upload element,
have to override this function and let it return true.
Creates a DOM identifier based on the name of the form,
the name of the component and an additional string.
The items will be chained using camel casing.
parameters
String | idPart | Optional string appended to component's id. |
returns
The DOM Id |
Function to render a component.
Subclasses of jala.Form.Component may override this function.
Function to validate a component.
Subclasses of jala.Form.Component may override this function.
parameters
jala.Form.Tracker | tracker | object tracking errors and holding parsed values and request data. |
Function to save the data of a component.
Subclasses of jala.Form.Component may override this function.
parameters
destObj | ||
val |
Returns an array containing the components
of this jala.Form.Component.Fieldset instance.
returns
The components of this jala.Form instance. |
Adds a component to this jala.Form.Component.Fieldset instance
parameters
jala.Form.Component.Input | component |
Returns true if this instance of jala.Form.Component.Fieldset
contains at least one component doing a file upload.
see
Sets the legend text.
parameters
String | newLegend | legend to use when printing the fieldset. |
Renders all components within the fieldset.
Validates all components within the fieldset.
parameters
jala.Form.Tracker | tracker |
Saves all components within the fieldset.
parameters
jala.Form.Tracker | tracker | |
Object | destObj |
Returns the handler object for the skin.
Sets the handler to use when rendering the skin.
By default, the form's data object is used a handler.
parameters
Object | newHandler | new skin handler object. |
Renders the skin named by this component to the response.
Sets a requirement for this component.
If function is called without arguments, jala.Form.REQUIRE
is set to true.
parameters
String | key | String defining the type of requirement, constants in jala.Form may be used. |
Object | val | Value of the requirement. |
String | msg | Optional error message if requirement is not fulfilled. |
Returns the requirement value for a given key.
parameters
String | key | String defining the type of requirement, constants in jala.Form may be used. |
Sets a custom error message
parameters
String | key | String defining the type of requirement, constants in jala.Form may be used. |
String | msg | Error message |
Returns a specific message for a config element.
parameters
String | key | The key of the message as defined by the constants in jala.Form.* (e.g. "require", "maxlength", "minlength" ... |
String | defaultMsg | the message to use when no message was defined. |
Object | args | One or more arguments passed to the gettext message processor which will replace {0}, {1} etc. |
returns
rendered message |
Sets the label for this component
parameters
String | newLabel | new label |
Returns the help text set for this component.
returns
help text |
Sets the help text for this component
parameters
String | newHelp | new help text |
Validates the input provided to this component. First,
checkRequirements is called. If no error occurs, the input
is parsed using parseValue and passed on to the validator
function.
parameters
jala.Form.Tracker | tracker | Tracker object collecting request data, error messages and parsed values. |
see
Saves the parsed value using setValue.
parameters
jala.Form.Tracker | tracker | Tracker object collecting request data, error messages and parsed values. |
Object | destObj | (optional) object whose values will be changed. |
see
Retrieves the property which is edited by this component.
- If no getter is given, the method returns the primitive property of the data object with the same name as the component.
- If a getter function is defined, it is executed with the scope of the data object and the return value is used as default value. The name of the component is passed to the getter function as an argument.
returns
The value of the property |
Sets a property of the object passed as argument to the given value.
If no setter is set at the component, the primitive property
of the data object is changed.
If a setter function is defined it is executed with the data object
as scope and with the name and new value provided as arguments
If the setter is explicitly set to null, no changes are made at all.
parameters
Object | destObj | (optional) object whose values will be changed. |
Object | value | The value to set the property to |
returns
True in case the update was successful, false otherwise. |
see
Renders this component including label, error and help messages directly
to response.
If the error tracker holds an error message for this component,
it is wrapped in a div-tag and returned as a string.
returns
Rendered string |
Returns the rendered label of this component
returns
The rendered label of this component |
If this component contains a help message, it is wrapped in
a div-tag and returned as a string.
returns
The rendered help message |
Renders this component including label, error and help messages
directly to response
Renders the control(s) of this component
Renders this component's error message (if set) directly to response
Renders this component's label.
Renders this component's help text, if set.
Renders this component's name
Renders this component's type
Renders this component's class name.
Note that this is just the class name that has been explicitly
assigned using setClassName.
see
Creates a new attribute object for this element.
returns
Object with properties id, name, class |
Checks user input for maximum length, minimum length and require
if the corresponding options have been set using the require method.
parameters
Object | reqData | request data |
returns
String containing error message or null if everything is ok. |
see
Checks user input against options set using the require method.
parameters
Object | reqData | request data |
returns
String containing error message or null if everything is ok. |
see
Parses the string input from the form and creates the datatype that
is edited with this component. For the input component this method
is not of much use, but subclasses that edit other datatypes may use
it. For example, a date editor should convert the user input from string
to a date object.
parameters
Object | reqData | request data |
returns
parsed value |
Renders the html form elements to the response.
This method shall be overridden by subclasses of input component.
parameters
Object | attr | Basic attributes for the html form elements. |
Object | value | Value to be used for rendering this element. |
Object | reqData | Request data for the whole form. This argument is passed only if the form is re-rendered after an error occured. |
Renders a password input tag to the response.
parameters
Object | attr | Basic attributes for this element. |
Object | value | Value to be used for rendering this element. |
Object | reqData | Request data for the whole form. This argument is passed only if the form is re-rendered after an error occured. |
Renders this component directly to response. For a hidden tag, this is
just an input element, no div tag or anything.
Renders a hidden input tag to the response.
parameters
Object | attr | Basic attributes for this element. |
Object | value | Value to be used for rendering this element. |
Object | reqData | Request data for the whole form. This argument is passed only if the form is re-rendered after an error occured. |
Returns the row numbers for this component.
returns
row numbers |
Sets the row numbers for this component.
parameters
String | newRows | new row numbers |
Returns the col numbers for this component.
returns
col numbers |
Sets the col numbers for this component.
parameters
String | newCols | new col numbers |
Renders a textarea input field to the response.
parameters
Object | attr | Basic attributes for this element. |
Object | value | Value to be used for rendering this element. |
Object | reqData | Request data for the whole form. This argument is passed only if the form is re-rendered after an error occured. |
Returns the date format for this component.
returns
date format object |
Sets the date format for this component.
parameters
String | newDateFormat | new date format |
Renders a textarea tag to the response.
parameters
Object | attr | Basic attributes for this element. |
Object | value | Value to be used for rendering this element. |
Object | reqData | Request data for the whole form. This argument is passed only if the form is re-rendered after an error occured. |
Validates user input from a date editor.
parameters
Object | reqData | request data |
returns
null if everything is ok or string containing error message |
Parses the string input from the form and converts it to a date object.
Throws an error if the string cannot be parsed.
parameters
Object | reqData | request data |
returns
parsed date value |
Returns the option list for this component.
Sets the option list for this component.
The argument may either be an array that will be used as option list,
or a function that is called when the option component is rendered and
has to return an option array.
For both arrays those formats are allowed:
Array of arrays
Array of objects
Array of strings
[ [val, display], [val, display], .. ]
[ {value:val, display:display}, .. ]
[ display, display, .. ]
In this case,
the index position of the string will be the value.parameters
Array Function | newOptions | Array or function defining option list. |
Returns the text that should be displayed if no value is selected.
Sets the text that is displayed if no value is selected
parameters
String | newFirstOption | text to display as first option element. |
Renders a dropdown element to the response.
parameters
Object | attr | Basic attributes for this element. |
Object | value | Value to be used for rendering this element. |
Object | reqData | Request data for the whole form. This argument is passed only if the form is re-rendered after an error occured. |
Validates user input from a dropdown element by making sure that
the option value list contains the user input.
parameters
Object | reqData | request data |
returns
string containing error message or null if everything is ok. |
see
Creates an array of options for a dropdown element or a
group of radiobuttons. If options field of this element's
config is an array, that array is returned.
If options is a function, its return value is returned.
returns
array of options |
Checks user input for optiongroups: Unless require("checkoptions")
has ben set to false, the user input must exist in the option array.
parameters
Object | reqData | request data |
returns
null if everything is ok or string containing error message |
Renders a set of radio buttons to the response.
parameters
Object | attr | Basic attributes for this element. |
Object | value | Value to be used for rendering this element. |
Validates user input from a set of radio buttons and makes sure that
option value list contains the user input.
parameters
Object | reqData | request data |
returns
null if everything is ok or string containing error message |
see
Renders an checkbox to the response.
parameters
Object | attr | Basic attributes for this element. |
Object | value | Value to be used for rendering this element. |
Parses the string input from the form. For a checked box, the value is 1,
for an unchecked box the value is 0.
parameters
Object | reqData | request data |
returns
parsed value |
Validates user input from checkbox.
parameters
Object | reqData | request data |
returns
null if everything is ok or string containing error message |
Renders a file input tag to the response.
parameters
Object | attr | Basic attributes for this element. |
Object | value | Value to be used for rendering this element. |
Object | reqData | Request data for the whole form. This argument is passed only if the form is re-rendered after an error occured. |
Validates a file upload by making sure it's there (if REQUIRE is set),
checking the file size, the content type and by trying to construct an image.
parameters
Object | reqData | request data |
jala.Form.Tracker | tracker | jala.Form.Tracker object storing possible error messages |
returns
null if everything is ok or string containing error message |
Validates an image upload by making sure it's there (if REQUIRE is set),
checking the file size, the content type and by trying to construct an image.
If the file is an image, width and height limitations set by require are
checked.
parameters
Object | reqData | request data |
Sets the value for this button.
parameters
String | newValue | new value |
Renders a button to the response.
parameters
Object | attr | Basic attributes for this element. |
Object | value | Value to be used for rendering this element. |
Object | reqData | Request data for the whole form. This argument is passed only if the form is re-rendered after an error occured. |
Creates a new attribute object for this button.
parameters
attr | ||
value |
returns
Object with all attributes set for this button. |
Creates a new attribute object for this button.
parameters
attr | ||
value |
returns
Object with all attributes set for this button. |
static default getter function used to return a field
from the data object.
parameters
String | name | Name of the property. |
static default setter function used to change a field
of the data object.
parameters
String | name | Name of the property. |
Object | value | New value of the property. |
Returns true if an error has been set for at least one component.
returns
true if form encountered an error. |
Returns the number of components for which this instance has
tracked an error.
returns
Number of components that did not validate. |