Romber

Form

The ROMBER_FORM.PHP script is a generic script used to manage a web form.

On this page:

• Synopsis
• Details
  • Callbacks
  • Form Details
  • Form Item Types
  • Form Item Attributes
  • Form Steps
• Examples
• See Also

Synopsis

require_once 'romber_form.php';
 .
 .
 .
romber_handle_form ( $form_details, $form_items [, $form_steps ] );

form_details

The form_details array is a list of form level options.

form_items

The form_items array is a list of form items which are displayed as part of the web form. Each element in the array is another array which descriptionribes the form item in detail.

form_steps

The form_steps array is a list of form steps which are followed as part of the web form. Each element in the array is another array which descriptionribes the form step in detail.

Details

Callbacks

Some form options and steps may specify a callback function. The prototype for a callback is:

function callback (
  romber_form $arg_form_details,
  romber_form_step $arg_step,
  $arg_phase )

The function may change values in $arg_form_details if the argument is specified as pass by reference (i.e. &$arg_form_details).

Form Details

Each form detail option has a name and value. The following options are supported:

$romber_config['preferences']['form_construction_default'] = 'DIV';
$romber_config['preferences']['form_construction_force'] = 'DIV';

Form Item Types

The form item array must have a type value. The following types are supported:

• breakcolumn
• breakgroup
• buttons
• captcha
• captcha.ejeliot
• captcha.google
• captcha.hn
• captcha.milki
• captcha.pear
• captcha.recaptcha
• captcha.simple
• checkbox
• code
• code.lower
• code.mixed
• code.upper
• country
• country_zone
• creditcard
• creditcard.4by4
• date.calendar
• date.ddmmm.pulldown.yyyy
• date.ddmmmyyyy.pulldown
• date.mmyyyy.pulldown
• datetime.calendar.hhmm
• datetime.ddmmmyyyy.pulldown.hhmm
• dependency.begin
• dependency.default
• dependency.end
• email.address
• file.select
• file.upload
• formula
• headings
• hidden
• info
• itemlist
• itemset
• merge.column
• merge.rows
• message
• message.confirm
• message.display
• message.input
• null
• number
• oneof.begin
• oneof.end
• password
• postcode
• radioset
• result
• select
• sequence
• split.column
• split.rows
• telephone
• text
• textarea
• time.hhmm
• time.hhmmss
• timer
• timestamp
• tracking
• username
• verifier
• viewhide.begin
• viewhide.end

breakcolumn

This layout form item indicates that a new column should be started when in multi-column layout.

Example:

array ( 'type' => 'breakcolumn' )

breakgroup

This layout form item indicates that a new group should be started within the current column when in multi-column layout.

Example:

array ( 'type' => 'breakgroup' )

buttons

This layout item allows a buttons row to be included other than at the top or bottom the form. See also buttons_at_bottom and buttons_at_top.

Example:

array (
  'type' => 'buttons' )

captcha, captcha.ejeliot, captcha.google, captcha.hn, captcha.milki, captcha.pear, captcha.recaptcha and captcha.simple

This input form item requests the user to enter as text a value displayed as an image or played as a sound. There are sereval variants including captcha.ejeliot, captcha.google, captcha.milki, captcha.hn, captcha.pear, captcha.recaptcha and captcha.simple.

The captcha.ejeliot variant uses the mechanism provided by E J Eliot.

The captcha.google variant uses the mechanism provided by Google which is a variant of reCAPTCHA.

The captcha.hn variant uses the mechanism provided by Horst Nogajski.

The captcha.milki variant uses the mechanism provided by Milki.

The captcha.pear variant uses the mechanism provided by PEAR.

The captcha.recaptcha variant uses the mechanism provided by reCAPTCHA. When using the captcha.recaptcha variant, privatekey and publickey are normally required.

The captcha.simple variant uses the mechanism provided by the PHP image functions. The image is generated dynamically and consists of size characters from the character set abcdefghkmnopqrstuvwxyz (note the absense of ijl).

Example:

array (
  'type' => 'captcha.simple',
  'prompt' => 'Enter confirmation',
  'description' => 'Confirmation',
  'size' => 6,
  'required' => TRUE )

checkbox

Example:

array (
  'type' => 'checkbox',
  'name' => 'found_friend',
  'prompt' => 'Friend' )

code, code.lower, code.mixed, code.upper and postcode

This input form item allows the entry of a valid code. Valid code characters include alphanumeric characters and the underscore. The code.mixed variant which also appies when no variant is specified, allows both lower and uppercaes characters in the code. The code.lower and code.upper variants only allow lowercase or uppercase characters respectivly. The postcode variant also allows spaces.

Example:

array (
  'name' => 'some_code',
  'type' => 'code',
  'prompt' => 'Some code',
  'size' => 31 )

country

Example:

array (
  'name' => 'country',
  'type' => 'country',
  'prompt' => 'Which country?',
  'required' => TRUE )

country_zone

Example:

array (
  'name' => 'country_zone_code',
  'type' => 'country_zone',
  'prompt' => 'Province/State/Territory',
  'required' => TRUE )

creditcard

This layout item allows data entry of a 14 to 16 digit credit card number. This will work for all credit cards including American Express, Bankcard, Diners Club, MasterCard and VISA.

Example:

array (
  'type' => 'creditcard',
  'name' => 'card_number',
  'prompt' => 'Card number',
  'required' => TRUE )

creditcard.4by4

This layout item allows data entry of a 16 digit credit card number in 4 groups of 4 digits. This will work for Bankcard, MasterCard and VISA. It will not work for American Express or Diners Club.

Example:

array (
  'type' => 'creditcard.4by4',
  'name' => 'card_number',
  'prompt' => 'Card number',
  'separate' => '-',
  'required' => TRUE )

Note that the default separate attribute value is a blank space.

date.calendar

Example:

array (
  'name' => 'date_calendar',
  'type' => 'date.calendar',
  'format' => '%Y-%m-%d',
  'prompt' => 'What date to you want?',
  'required' => TRUE )

date.ddmmm.pulldown.yyyy

Example:

array (
  'name' => 'when',
  'type' => 'date.ddmmm.pulldown.yyyy',
  'prompt' => 'Date of birth',
  'required' => TRUE )

date.ddmmmyyyy.pulldown

Example:

array (
  'name' => 'when',
  'type' => 'date.ddmmmyyyy.pulldown',
  'prompt' => 'When do you want to move?',
  'required' => TRUE )

date.mmyyyy.pulldown

Example:

array (
  'name' => 'card_expiry',
  'type' => 'date.mmyyyy.pulldown',
  'prompt' => 'Card Expiry',
  'required' => TRUE )

datetime.calendar.hhmm

Example:

array (
  'name' => 'open_timestamp',
  'type' => 'datetime.calendar.hhmm',
  'prompt' => 'Opening date and time',
  'required' => TRUE )

datetime.ddmmmyyyy.pulldown.hhmm

Example:

array (
  'name' => 'open_timestamp',
  'type' => 'datetime.ddmmmyyyy.pulldown.hhmm',
  'prompt' => 'Opening date and time',
  'required' => TRUE )

dependency.begin

This layout form item indicates the beginning of a dependency block. The item which controls the dependency block must have the same item name as the block.

Example:

array ( 'type' => 'dependency.begin', 'name' => 'dependent_data' )

dependency.default

This layout form item specifies the defaut dependency value for subsequent items within a dependency block. This saves using the dependency item attribute for every item in the block.

Example:

array ( 'type' => 'dependency.default', 'value' => '2' )

dependency.end

This layout form item indicates the end of a dependency block.

Example:

array ( 'type' => 'dependency.end' )

email.address

Example:

file.select

Example:

file.upload

Example:

formula

Example:

array (
  'name' => 'price',
  'type' => 'formula',
  'prompt' => 'Price',
  'script' => 'romber_update ( romberform );',
  'size' => 7 )

headings

This layout item provides a list of column headings. When in multi-column layout, the headings apply to the inner columns, not the outer columns. By default there are no column headings. Normally, this item would appear before any displayable items.

Example:

array (
  'type' => 'headings',
  'valign' => 'bottom',
  'value' => array (
    array ( 'align' => 'right', 'value' => 'BEDROOMS' ),
    array ( 'align' => 'left',  'value' => 'Qty' ),
    array ( 'align' => 'center', 'value' => 'm<sup>3</sup>' )) )

hidden

Example:

array (
  'name' => 'quoted_hourly_rate',
  'type' => 'hidden',
  'prompt' => 'Hourly rate',
  'confirm' => TRUE,
  'display' => TRUE,
  'step' => 'final',
  'value' => '$50' )

info

Displays like message, otherwise behaves much like text. More specifically, info items do not use POST variables.

Example:

array (
  'name' => 'truck_type_name',
  'type' => 'info',
  'prompt' => 'Truck type',
  'step' => 'final',
  'value' => 'Large' )

itemlist

Displays a two column select list with Add, All, Remove and None buttons to move items between the excluded and included lists. The cols attribute specifies the width of each column. The rows attribute specifies the height of each column. If necessary, the columns will have vertical scroll bars. An itemlist can be ordered by position in the select array or by descriptionription.

Example:

array (
  'name' => 'colours_available',
  'type' => 'itemlist',
  'prompt' => 'Colours available',
  'step' => 'final',
  'select' => array (
    array ( 'description' => 'Black', 'value' => '000000' ),
    array ( 'description' => 'Blue', selected' => TRUE, 'value' => '0000FF' ),
    array ( 'description' => 'Cyan', 'value' => '00FFFF' ),
    array ( 'description' => 'Green', selected' => TRUE, 'value' => '00FF00' ),
    array ( 'description' => 'Magenta', 'value' => 'FF00FF' ),
    array ( 'description' => 'Red', selected' => TRUE, 'value' => 'FF0000' ),
    array ( 'description' => 'White', 'value' => 'FFFFFF' ),
    array ( 'description' => 'Yellow', 'value' => 'FFFF00' ) ),
  'cols' => 8,
  'rows' => 10 )

itemset

Displays a select list with Add and Remove buttons to add and remove items from the list. The cols attribute specifies the width of the list. The rows attribute specifies the height of the list. If necessary, the list will have a vertical scroll bar.

Example:

array (
  'name' => 'colours_available',
  'type' => 'itemset',
  'prompt' => 'Colours available',
  'step' => 'final',
  'select' => array (
    array ( 'description' => 'Black', 'value' => '000000' ),
    array ( 'description' => 'Blue', 'value' => '0000FF' ),
    array ( 'description' => 'Cyan', 'value' => '00FFFF' ),
    array ( 'description' => 'Green', 'value' => '00FF00' ),
    array ( 'description' => 'Magenta', 'value' => 'FF00FF' ),
    array ( 'description' => 'Red', 'value' => 'FF0000' ),
    array ( 'description' => 'White', 'value' => 'FFFFFF' ),
    array ( 'description' => 'Yellow', 'value' => 'FFFF00' ) ),
  'cols' => 8,
  'rows' => 10 )

merge.column

This layout form item indicates that a split column should be merged back into a single column.

Example:

array ( 'type' => 'merge.column' )

merge.rows

This layout form item indicates that split rows should be merged back into a single column.

Example:

array ( 'type' => 'merge.rows' )

message message.confirm message.display message.input

Display only. No associated value handling.

The message.phase items indicate messages only displayed during the specified phase. By default the message type is displayed in all phases. The most useful is probably message.input which proved messages specific to the input phase. These messages might contain additional helpful information for the user.

Example:

array (
  'type' => 'message',
  'value' => 'This is a message' )

null

Example:

number

Example:

oneof.begin

This layout form item indicates the beginning of a one of block.

Example:

array ( 'type' => 'oneof.begin' )

oneof.end

This layout form item indicates the end of a one of block.

Example:

array ( 'type' => 'oneof.end' )

password

This form item allows etry of a password with asterisk display of the entered characters.

Example:

array (
  'name' => 'username_password',
  'type' => 'password' )

radioset

Example:

array (
  'name' => 'card_type',
  'type' => 'radioset',
  'prompt' => 'Card Type',
  'required' => TRUE,
  'select' => array (
    array ( 'description' => 'American Express', 'value' => 'American Express' ),
    array ( 'description' => 'Bankcard', 'value' => 'Bankcard' ),
    array ( 'description' => 'Diners Club', 'value' => 'Diners Club' ),
    array ( 'description' => 'Mastercard', 'value' => 'Mastercard' ),
    array ( 'description' => 'Visa', 'value' => 'Visa' ) ))

result

Example:

select

Example:

array (
  'name' => 'where',
  'type' => 'select',
  'prompt' => 'Where are you moving to?',
  'select' => array (
    array ( 'description' => 'within metro Melbourne',
            'value' => 'within metro Melbourne',
            'selected' => TRUE ),
    array ( 'description' => 'Metro Melbourne to regional Victoria',
            'value' => 'Metro Melbourne to regional Victoria' ),
    array ( 'description' => 'Melbourne to interstate',
            'value' => 'Melbourne to interstate' ) ) )

sequence

Example:

split.column

This layout form item indicates that a single column into multiple columns. The cols attribute specifies the number of columns. The default number of columns is 2. Subsequent items are displayed top to bottom left to right until a merge.column item.

Example:

array (
'type' => 'split.column',
'cols' => 3 )

split.rows

This layout form item indicates that a single column into multiple columns. The cols attribute specifies the number of columns. The default number of columns is 2. Subsequent items are displayed left to right top to bottom until a merge.rows item.

Example:

array ( 'type' => 'split.rows' )

telephone

Example:

array (
  'name' => 'Phone',
  'type' => 'telephone',
  'prompt' => 'Phone',
  'size' => 20,
  'required' => TRUE )

text

Example:

array (
  'name' => 'account_number',
  'type' => 'text',
  'prompt' => 'Account number',
  'size' => 7,
  'required' => TRUE )

textarea

Example:

array (
	'name' => 'content',
	'type' => 'textarea',
	'editors' => 'wysiwyg',
	'prompt' => 'Content',
	'rows' => 10,
	'cols' => 60 )

time.hhmm

Example:

array (
  'name' => 'begin_time',
  'type' => 'time.hhmm',
  'prompt' => 'Commences at',
  'required' => TRUE )

time.hhmmss

Example:

array (
  'name' => 'begin_time',
  'type' => 'time.hhmmss',
  'prompt' => 'Commences at',
  'required' => TRUE )

timer

timestamp

Example:

array (
  'type' => 'timestamp',
  'name' => 'Timestamp',
  'prompt' => 'Date & Time',
  'format' => '%Y-%m-%d %H:%M' )

tracking

Return the IP address of the form submitter.

Example:

array (
  'type' => 'tracking',
  'subitems' = array (
    array ( 'item' => 'remoteaddress', 'prompt' => 'IP Address' )
  )
)

username

Example:

verifier

This form item request a form verifier to be used. The verifier tries to check that the form submission is not performed by a robot.

Example:

array (
  'type' => 'verifier',
  'prompt' => 'Verifier' )

viewhide.begin

This layout form item indicates the beginning of a view/hide block.

Example:

array ( 'type' => 'viewhide.begin', 'name' => 'lots_of_optional_data' )

viewhide.end

This layout form item indicates the end of a view/hide block.

Example:

array ( 'type' => 'viewhide.end' )

Form Item Attributes

Each form item array is a list of attribute names and values. The following attributes are supported:

'editors' => 'wysiwyg'

'editors' => array (
  'plain',
  'wysiwyg' )

'editors' => array (
  'plain',
  'wysiwyg' => array ( ... ) )

Form Steps

Each form step array is a list of attribute names and values.

Some attributes may specify a callback.

The following attributes are supported:

The followng notes apply to form steps:

• If no form_steps argument is specified, or the argument is empty, a single form step is implied by default. This implicit single form step is equivalent to:

  array (
    'begin' => '',
    'break' => FALSE,
    'confirm' => FALSE,
    'display' => TRUE,
    'end' => '',
    'execute' => TRUE,
    'input' => TRUE,
    'middle' => '',
    'name' => 'singlepage',
    'validate' => TRUE )

• If the last form step in the list doesn't specify a next form step, it should specify a display phase.

Examples

• Buttons Form - a form with extra button rows
• Calculator Form - a calculator form
• Captcha Form - a captcha form
• CGI Form - a CGI form
• Contact Form - a contact form
• Countries Form - a form with country selection
• Date & Time Form - a form with various dates and times
• Dependency Form - a form with items dependent on other items
• Editor Form - an editor form
• File Upload Form - a file upload form
• General Form - a general form
• Item List Form - a form with an item list
• Item Set Form - a form with an item set
• Member Form - a member details form
• Multi-Page Form - a multi-page form
• Order Form - an order form
• Payment Form - a payment form
• Popup Form - a form with a popup
• Shadow Prompt Form - a shadow prompt form
• Single Column Form - a single column form
• Split Column Form - a split column form
• Split Rows Form - a split rows form
• View/Hide Form - a view/hide form
• Wait Form - a wait on submit form