dbForm - Create, validate and process HTML forms based on Database Tables
dbForm is a PHP class that will create a Web Form for a database table and handles all processing of the form including validation of data, inserts, updates and deletes. Very customisable and flexible. Uses ADODB to connect to any database. Uses a simple Template to display the form. Looks for the following tags
{:template=""}
Includes another template inside the current one.
{:action=""}
{:end action}
Includes a section of html only if the current form action matches the actions in the list. The action list is a comma seperated list of all of the actions e.g. "select,update". The actions match buttons. See the method list for details of the default buttons and adding/removing buttons.
{:each field=""}
Loads a new template file for each field on the form
{:each field}
{:end field}
Repeats the code between the tags for each field on the form
{:fieldname}
Displays the name of the field. Only usable inside {:each field} tags
{:field}
Displays the field. Only usable inside {:each field} tags
Can contain attributes that will be applied to each field
e.g. {:field style="color: blue;"} will add the attribute style="color: blue;" to each field
{:field=""}
Displays the selected Field
Can contain attributes that will be applied to the field
e.g. {:field="firstname" style="color: blue;"} will add the attribute style="color: blue;" to firstname field
{:#fields}
Returns the number of visible fields
{:each button=""}
Loads a new template file for each button on the form
{:each button}
{:end button}
Repeats the code between the tags for each button on the form
{:button}
Display the button. Only usable inside {:each button} tags
Can contain attributes that will be applied to each button
e.g. {:button style="color: blue;"} will add the attribute style="color: blue;" to each button
{:button=""}
Displays the selected button
Can contain attributes that will be applied to the button
e.g. {:button="update" style="color: blue;"} will add the attribute style="color: blue;" to update button
{:#buttons}
Returns the number of buttons
{:hidden}
Displays all of the hidden fields
Can contain attributes that will be applied to each hidden field
e.g. {:hidden style="color: blue;"} will add the attribute style="color: blue;" to each hidden field
{:formname}
Displays the name setup in the initial creation of the form
{:form}
Displays the opening form tag. You will have to put the closing tag yourself.
Can contain attributes that will be applied to the form tag
e.g. {:form style="color: blue;"} will add the attribute style="color: blue;" to the form tag
{:status}
Display any status messages from the form.
Located in Program_Root/dbform.inc (line 292)
template | --dbForm
Whether to always update the current record before processing
Updates the record first if moving to another record.
Boolean whether to force the update of empty fields
This is used to fix an issue where resetting populated fields to empty are not saved. suggested by Keith Powers
Boolean for hashing password fields
Requires the mhash extension to be loaded
Boolean whether to use magic quoting (See PHP get_magic_quotes_gpc())
Used to determine how to handle quoted data for getUpdateSQL and getInsertSQL
Boolean for using validation
Currently validates not null and max lengths of fields
Version of dbForm
Class constructor
Create a dbForm based on a database table. If a table is set calls _prepareFields to determine the fields in the table Note however that no table is required and the form can be created manually Name will be stripped on any whitespace before being used so that javascript can find the form easily based on name
Adds a button to the buttons array
Type can be submit, button or image. Image buttons require the dbForm.js file or javascript errors will occur. Image buttons use a hidden field called dbform_imagerequesttype for processing
Adds a new field to the form at the end of the list
Creates a new fieldForm object and stores it in the class.
Changes the button type
Can change the type to cubmit, button or image. Image buttons require the dbForm.js file or javascript errors will occur. Image buttons use a hidden field called dbform_imagerequesttype for processing.
Changes the Types of a field
Cannot set to radio or checkbox with this method. Radio is not supported and checkbox has its own method (See setCheckBox)
Removes all of the buttons and processingFunctions if set
Displays the Form and all of its fields
Only very simple at the moment but will eventually need to be able to display the form in a layout dependant on set properties and also be able to display only parts of the form depending on the previous actions
Sets and returns the form action based on the parameters passed
Created as a seperate function so that it can be processed early if the need should arise. Looks at the requesttypes passed and sets the _formAction property and returns this as a value. Can be used to selectively create parts of the form depending on the action Note: If called before all buttons are added then it may not return the correct action. Defaults to dbform_null.
Calls the specified function to retrieve the select values
Select functions will be passed the following parameters. $value is the value of the current selected item. $action is the current action being processed.
Select functions should return an array of items in the following format: $options[0]["value"]=1 $options[0]["text"]="Some Text" $options[0]["selected"]=true // only if $value = 1 $options[0][any other attributes]=something;
Retrieves the values for a select list based on a query
Primarily used for foreign key lists must be called after process form so that the value for the field already exists _conn must be set If using filtering then this is not used.
Orders the buttons incase they need to be displayed in order
Only easy way to do this is create a tempory array and add items to it in order
Orders the fields based on an array of field names
Any fields not placed in the order will be placed at the end of the list in the order they are in the current list
Determines what to do with any data passed thru the form
Does some preprocessing on any field data returned.
Determines the action to perform.
Calls the appropriate internal or external function to perform the action.
Processes any filters if required.
Processes a template and returns the html for it
Removes a button
Only easy way to remove a button is to add everything except the button to a tempory array and then assign the tempory array to _buttons
Removes the indicated field from the field list
Field still exists but will not be displayed.
Sets the status message for a given action
Allows setting of the default status message to use for a specified action Can only be called before processForm
Note: Does not validate that the action is possible. i.e. actions usually equate to button names but this will NOT validate that a button of that name exists because to do so would not enable setting of the "null" action status. Also means that status messages could be set before the buttons are created.
Sets the Attributes for All buttons
Updates Field Attributes of All fields
Sets Form Attributes
Sets any attributes required for the form, if not already set on class creation.
Sets the Attributes for a button
Sets a field to be a checkbox and defines the values for it
The checkValue and uncheckValue parameters are the values that will be stored in the database if the checkbox is checked or unchecked
Updates Field Attributes
Set the Max Length field validation property
Note: Max length is set but ignore during display for certain fields such as select and checkboxes Requires the template to include the dbForm.js file or javascript errors will occur
Set the Not Null field validation property
Requires the template to include the dbForm.js file or javascript errors will occur
Sets the title of the selected field
We are going to enforce that this be done before formProcess but this is not strictly necessay as it doesnt effect processing
Sets the titles of many fields
Accepts an associative array of fields and titles. We are going to enforce that this be done before formProcess but this is not strictly necessay as it doesnt effect processing.
Sets a filter group for a select list
The filter query will be run first and the data displayed in the search list in an attempt to limit the search records displayed. Builds the filter list based on a array of filter groups Currently only the earch field can be filtered. Only stores data in the selectList array. Processing is done later. NOTE: Hidden fields are added to the form to help with filter processing
Sets a filter Page for a select list
The filter query will be run first and the data displayed in the search list in an attempt to limit the search records displayed. Build filter by creating groups of X records.
Uses SELECT LIMIT queries or the ADODB simulated equivilent.
Currently only the earch field can be filtered.
Only stores data in the selectList array. Processing is done later.
NOTE: Hidden fields are added to the form to help with filter processing
Sets a filter query for a select list
The filter query will be run first and the data displayed in the search list in an attempt to limit the search records displayed. Uses similar parameters to setSearchField. Currently only the search field can be filtered. Only stores data in the selectList array. Processing is done later. NOTE: Hidden fields are added to the form to help with filter processing
Sets the function to be called to process an action
Validates the actions exists before setting Processing functions will be passed the following parameters.
&$conn
The database connection that can be used to process the action.
$table
The table that the form is built for.
$httpvars
Array of the _GET or _POST variables passed to the form.
$httpfiles
Array of the _FILES variables passed to the form. Used for file upload processing.
$searchField
The field used to search by. Set by the setSearchField() method.
$searchid
The value returned from the search field.
$action
The form action to process.
These parameters are general enough that it is possible to create a single function to process all form actions if desired.
Processing functions should return an array of values for the fields If no values are needed return an empty array e.g.
$returnValues["personid"]["value"]=2;
$returnValues["lastname"]["value"]="Smith";
$returnValues["firstname"]["value"]="John";
Sets the field to be used for searching (usually the primary key)
Requires a query to display the list. Query requires first field to be the index, any extra fields will be displayed concatenated together by the glue field. The default text if any is displayed as the first item in the list. Auto selection is used to simplify form processing, otherwise the select button must be used to selected the record. Changes the field to be a hidden field and creates a new field called dbform_searchid that the selection list will appear as. NOTE: This means you MUST have a field in your template called dbform_searchid for this to work
Sets the field to be used for searching (usually the primary key)
Also sets the function to call to populate the field
Changes the field to be a hidden field and creates a new field called dbform_searchid that the selection list will appear as.
NOTE: This means you MUST have a field in your template called dbform_searchid for this to work
Search functions will be passed the following parameters.
$value is the value of the current selected item.
Search functions should return an array of items in the following format:
$options[0]["value"]=1
$options[0]["text"]="Some Text"
$options[0]["selected"]=true // only if $value = 1
$options[0][any other attributes]=something;
Sets the Sequence to use for the table in the form
Uses ADODB GenId which should create the sequence if it does not exist Emulates sequences for those databases that do not support them
Sets the Sequence Function to use for the table in the form
Function will be called on insert to determine the new primary key for the table Really only useful if you need to produce a non standard key that cannot be generated by a sequence
Sets the current Status Message
Hardcodes the status message reguardless of the current action. Can be called at any time.
Inherited From template
template::template()
template::display()
template::processTemplate()
template::replace()
template::setTemplateFile()
Documention generated on Sun, 14 Sep 2003 18:35:15 +1000 by phpDocumentor 1.2.1