Help And Documentation

2: Object Reference

2.10: The Data Form Object

A Form object can be used primarily to add and edit data in the site's database. It can also be used as a login form which will automatically search for database rows that match username fields, validate any password fields and give the opportunity for session variables to be set inside of the Success Content method.

It also allows formatting values to be set so that you can change the generated HTML of the form and additionally allows you to override the generated HTML completely by supplying your own form HTML and which POST data field to look for when the form is submitted to be processed.

When a form is submitted, validation rules can be applied and any image files that have been uploaded can be automatically processed (such as resizing) and saved again by using an Image object.


Set Action

This method can only be used once.

This method chooses the action performed by this form.

Action Description
Post Data A form will be generated but will not have any effect on the database. All data will be available as normal data variables of type 'Post Data'.
Log In When the form is submitted, a database query will search for one row using any fields and their submitted values that have been added with the type 'Username'. It will then validate any password fields that have been added with the type 'Password'. If successful, success content and then success redirect will be executed. It unsuccessful, failure content will be executed.
Show Data This option will generate a form with the data of the database row that it finds. It will not perform any other action.
Add Data When the form is submitted, the form will insert a row into the database.
Update Data When the form is submitted, the form will update a database row depending on the Query Condition object that has been added to this object.
Delete Data When the form is submitted, the form will delete from the database depending on the Query Condition object that has been added to this object.

Parameters

Name Text Variable Object Array
Action Yes No No No

Set Table

This method can only be used once.

This method sets the table which is used when selecting, adding, editing or deleting data, as well as finding and validating a user when logging in.

Parameters

Name Text Variable Object Array
Table Yes No No No

Query Condition

This method can only be used once.

This method allows you to add a Query Condition object so that if you are showing, editing or deleting data you only affect the row that you need to be affected. If also allows you to add additional constraints to the database query that is performed when searching for users when logging in.

Parameters

Name Text Variable Object Array
Condition No No Yes No

Add Field

This method can be used multiple times.

This method can be used to set a data variable.

This method automatically escapes database values.

This method allows you to add a field to the form that is generated by this object. You can also select the type of field, its name (which is the label displayed to the left of the field) and a default value which will override any value that comes from the database result row.

Hidden values are not sent to the web browser as hidden fields in the HTML but are instead available as data variables in the success content when it is executed. You might want to add a hidden value when adding data to the database to set specific values or to have access to certain fields in the success content when a user logging in has been successfully validated.

The password type will automatically hash any password submitted before it is inserted into or updated in the database.

The public and private file types will make the form prompt for a file to be uploaded and automatically store the file in either a publically accessible or private directory.

Parameters

Name Text Variable Object Array
Field Yes No No No
Type Yes No No No
Name Yes No Yes No
Value Yes Yes Yes No

Add Field Value

This method can be used multiple times.

This method automatically escapes database values.

This method can be used to add values as options if you have a field which generates a drop-down (select) box or radio buttons.

Parameters

Name Text Variable Object Array
Field Yes No No No
Name Yes No Yes No
Value Yes No Yes No

Add Field Values Query

This method can be used multiple times.

This method can be used to add values as options if you have a field which generates a drop-down (select) box or radio buttons. It does this by taking the database result and using the first field it finds as the value and the second field it finds as the label to display.

Parameters

Name Text Variable Object Array
Field Yes No No No
Database Query No No Yes No

Add Validation

This method can be used multiple times.

This method allows you to add validation rules to your form which will prevent the form's action from happening if any of the rules are not satisfied. It will display any error messages you have provided before the form is generated.

Some validation rules require you to specify a value in the value parameter, for example, a 'Minimum Length' rule expects a number which is the minimum number of characters of text allowed.

Parameters

Name Text Variable Object Array
Field Yes No No No
Rule Yes No No No
Value Yes No Yes No
Error Yes No Yes No

Manipulate Uploaded Image

This method can be used multiple times.

This method allows you to add an image object which can be used to manipulate an image, such as resizing it, before saving the file.

Parameters

Name Text Variable Object Array
Field Yes No No No
Image No No Yes No

Submit Button

This method can only be used once.

This method allows you to set the HTML which represents the submit button of the form.

Parameters

Name Text Variable Object Array
Submit Yes No Yes No

Set Insert ID Variable

This method can only be used once.

This method can be used to set a data variable.

This method is used to set a data variable with a specific name which contains the automatically generated ID value of the row which has just been inserted into a database table. This is useful because this ID value can then be used in the success content or success URL of this form when it is executed in order to set other variables, perform other database queries or redirect to a URL that contains the newly created ID value.

Parameters

Name Text Variable Object Array
Name Yes Yes No No

Success Content

This method can be used multiple times.

This method allows you to add content that will be displayed or executed after this form has successfully been submitted and completed its action.

Parameters

Name Text Variable Object Array
Content Yes Yes Yes No

Set Success Redirect

This method can be used multiple times.

This method allows you to add a URL which the web browser is redirected to after this form has successfully been submitted and completed its action.

Parameters

Name Text Variable Object Array
Url Yes Yes Yes No

Failure Content

This method can be used multiple times.

This method allows you to add content that will be displayed or executed after this form has been submitted but has failed to complete its action.

Parameters

Name Text Variable Object Array
Failure Yes Yes Yes No

Set Form Content

This method can only be used once.

This method allows you to manually override the generated HTML completely by supplying your own form HTML. If you use this method you must specify which POST data field to look for when the form is submitted so that it can be processed.

Parameters

Name Text Variable Object Array
Content Yes No Yes No

Postback Field

This method can only be used once.

This method allows you specify which POST data field to look for when the form is submitted so that it can be processed.

Parameters

Name Text Variable Object Array
Field Yes No Yes No

Set Formatting

This method can only be used once.

This method can be used to specify the HTML which formats the form and fields that are generated by this object. Using this method will override the default site formatting values.

Parameters

Name Text Variable Object Array
Form CSS class Yes No Yes No
Before the form Yes No Yes No
Before a row Yes No Yes No
Before a label Yes No Yes No
After a label Yes No Yes No
Before a field Yes No Yes No
After a field Yes No Yes No
After a row Yes No Yes No
Between rows Yes No Yes No
After the form Yes No Yes No
Field CSS class Yes No Yes No
Before the errors Yes No Yes No
Before an error Yes No Yes No
After an error Yes No Yes No
After the errors Yes No Yes No
Select Value Text Yes No Yes No

Next Page » « Previous Page