auForm

The auForm class is part of the auLib package. Its purpose is to build form objects that can be used to output HTML and perform simple user input validation. It also attempts to fool spammers using a couple methods which should be undetectable by actual people. The included auForm.css should be integrated into sites using auForm in order to make sure the spam trap fields do not get seen by actual people.

Hierarchy

auFormElement
- auFormContainer
  - auForm

Usage

Create a form using new auForm(), then build it using Add(). Check Submitted() to see if the form was submitted, or to find out which submit button was used. Use CheckInput() to automatically validate fields. Use WriteHTML() to write out HTML code for the form. If any errors were found during CheckInput(), they will display above the problematic field.

Constants

Field Types

_AU_FORM_FIELD_NORMAL
_AU_FORM_FIELD_NUMERIC
_AU_FORM_FIELD_INTEGER
_AU_FORM_FIELD_DATETIME
_AU_FORM_FIELD_MULTILINE
_AU_FORM_FIELD_BBCODE
_AU_FORM_FIELD_PASSWORD
_AU_FORM_FIELD_CHECKBOX
_AU_FORM_FIELD_FILE

Select Types

_AU_FORM_SELECT_DROPDOWN
_AU_FORM_SELECT_RADIO

MultiSelect Types

_AU_FORM_MULTI_LIST
_AU_FORM_MULTI_CHECK

Public Functions

new auForm

new auForm($id, $action, $method, $defaultonly)

Creates a new form object.

$id = CSS id of the form element. Also the value of formid data field.
$action = Script to send form data to. This value will automatically be HTML encoded. Defaults to the current page without a querystring.
$method = How to send form data. Defaults to HTTP POST ('post') -- can be overridden to GET ('get').
$defaultonly = Whether the fields should only use their default values and not the values present in POST or GET. Defaults to using POST or GET values if present.

Add

Add($element)

Adds an element to the form.

$element = An auFormElement object.
@return = The added auFormElement, or false.

AddFieldSet

AddFieldSet($fieldset)

Deprecated: Use Add(new auFormFieldSet(...)) instead.

Adds a fieldset to the form.

$fieldset = An auFormFieldSet object, with all of its elements already added.

AddData

AddData($name, $value)

Deprecated: Use Add(new auFormData(...)) instead.

Adds data to the form that will not display but will be submitted.

$name = Name to submit the data as.
$value = Value of the data.

AddText

AddText($title, $text)

Deprecated: Use Add(new auFormText(...)) instead.

Adds text to the form that will display but will not be submitted.

$title = Title of the text, which displays like a field label.
$text = Text to display.

AddHTML

AddHTML($title, $html)

Deprecated: Use Add(new auFormHTML(...)) instead.

Adds HTML to the form that will display but will not be submitted. This can also be used to add custom fields, but they will have to be validated manually.

$title = Title of the text, which displays like a field label.
$html = The text to display.

AddField

AddField($name, $label, $tooltip, $required, $default, $type, $width, $maxlength)

Deprecated: Use Add() with the appropriate auFormElement instead.

Adds a field to the form.

$name = Name to submit the field as.
$label = Label to display with the field. Default is blank.
$tooltip = Tooltip text to display when the mouse is over the label. For checkbox fields, the tooltip displays next to the checkbox itself. Default is none.
$required = Whether a value is required in this field. Default is not required. Ignored for some field types.
$default = Default value for this field. Default is blank / unchecked.
$type = Type of field. Should be an _AU_FORM_FIELD_* value.
$width = Width of the field in characters. Default is browser default.
$maxlength = The maximum number of characters the field can accept. Default is unlimited. Ignored for checkboxes and file fields.

AddSelect

AddSelect($name, $label, $tooltip, $values, $default, $type)

Deprecated: Use Add(new auFormSelect(...)) instead.

Adds a one-value selection field to the form.

$name = Name to submit the field as.
$label = Label to display with the field. Default is blank.
$tooltip = Tooltip text to display when the mouse is over the label. Default is none.
$values = Associative array of possible values (value => display text). If values and display text are all identical, a normal array can be passed through auFormSelect::ArrayIndex($array) to get it into the appropriate format. Default is no possible values.
$default = Default value for this field. Default is browser default, which is usually the first of the possible values.
$type = Type of field -- set to _AU_FORM_SELECT_RADIO to use radio buttons. Default is _AU_FORM_SELECT_DROPDOWN for a dropdown selection.

AddMultiSelect

AddMultiSelect($name, $label, $tooltip, $values, $default, $type)

Deprecated: Use Add(new auFormMultiSelect(...)) instead.

Adds a multiple-value selection field to the form.

$name = Name to submit the field as.
$label = Label to display with the field. Default is blank.
$tooltip = Tooltip text to display when the mouse is over the label. Default is none.
$values = Associative array of possible values (value => display text). If values and display text are all identical, a normal array can be passed through auFormSelect::ArrayIndex($array) to get it into the appropriate format. Default is no possible values.
$default = Array of default values for this field. Default is for no values to be selected.
$type = Type of field -- set to _AU_FORM_MULTI_LIST to use list box. Default is _AU_FORM_MULTI_CHECK for checkboxes.

AddButtons

AddButtons($text, $tooltip, $name)

Deprecated: Use Add(new auFormButtons(...)) instead.

Adds submit buttons to the form.

$text = Text to display on the button. Pass an array to have multiple buttons on one line.
$tooltip = Tooltip text to display when the mouse is over the button. Pass an array parallel to $text if $text was an array. Default is none.
$name = Name that should be used for the button. Must be the same for all buttons. Default is 'submit'.

WriteHTML

WriteHTML($trusted, $indent)

Writes out the form in HTML format. If any fields have failed their check, error messages will be displayed above the field.

$trusted = Whether the submitter is trusted. This essentially disables anti-spam measures and is intended to be set true for logged-in users. Default is not trusted, which means anti-spam measures are enabled.
$indent = A string of white space to help line the form up with the rest of the HTML. Default is six spaces.

Submitted

Submitted()

Checks if the form has been submitted.

@return = Text of the button used to submit the form, or false if the form was not submitted.

CheckInput

CheckInput($trusted)

Checks all the form fields for invalid input.

$trusted = Whether the submitter is trusted. This essentially disables checking anti-spam measures and is intended to be set true for logged-in users. This should match the value passed to WriteHTML(). Default is not trusted, which means anti-spam measures are checked.
@return = True if all fields are valid.

Examples

E-mail Contact Form

This code creates a form that submits to the same script for sending e-mail.

require_once 'auForm.php';
// build the form
$emailform = new auForm('emailform');
$emailform->Add(new auFormString('name', 'Your Name', 'Enter your name for the return address on the e-mail', true));
$emailform->Add(new auFormString('email', 'Your E-mail', 'Enter your e-mail address so that you can get a reply', true, , , , _AU_FORM_STRING_EMAIL));
$emailform->Add(new auFormString('subject', 'Subject', 'Enter the subject of your message'));
$emailform->Add(new auFormMultiString('message', 'Message', 'Enter your message', true));
$emailform->Add(new auFormButtons('Send', 'Send this message'));

// check if the form was submitted
if($emailform->CheckInput()) {
  // at this point, we know we have a name, e-mail address, and message
  // subject may be blank since it was not marked required
  // NOTE: additional checks should be performed to avoid the possibility of e-mail injection!  Consider using auSend::Email
  mail('admin@example.com', 'Contact form: ' . $_POST['subject'], $_POST['message'], 'From: ' . $_POST['name'] . ' <' . $_POST['email'] . '>');
  echo 'mail sent!';
} else
  // show the form if it either wasn't submitted or was missing a required field
  $emailform->WriteHTML();

auForm

Contents

Usage

Constants

Field Types

Select Types

MultiSelect Types

Public Functions

new auForm

Add

AddFieldSet

AddData

AddText

AddHTML

AddField

AddSelect

AddMultiSelect

AddButtons

WriteHTML

Submitted

CheckInput

Examples

E-mail Contact Form

Navigation menu

auForm

Usage

Constants

Field Types

Select Types

MultiSelect Types

Public Functions

new auForm

Add

AddFieldSet

AddData

AddText

AddHTML

AddField

AddSelect

AddMultiSelect

AddButtons

WriteHTML

Submitted

CheckInput

Examples

E-mail Contact Form

Navigation menu

Search