Libraries: Form

Getting Started

To use a form in a view you have to define one. This will be done in form of a declaration-file and at least one language-file.

• Every form have its own declaration file and all them are saved in the directory "application/forms". The name of the file is the name of the form. The extension is alway ".php"
• The language-files of the form have to be saved into "application/language/LANGUAGE". The name of the files must be "form_FORMNAME_lang.php".

The declaration file contains all fields and it's definitions:

$form['gender']=array(
   'type'=>'dropdown',
    'options'=>array('male','female'),
    'rules'=>'required'
);
$form['firstname']=array(
   'type'=>'text',
   'rules'=>'required'
);
$form['lastname']=array(
   'type'=>'text',
   'rules'=>'required'
);
$form['email']=array(
   'type'=>'text',
   'rules'=>'required|valid_email'
);

The language file contains the labels, options, error messages etc. in the desired language:

$lang['form_fields']=array(
    'gender'=>array(
        'label'=>'Geschlecht',
        'options'=>array('male'=>'Männlich','female'=>'Female')
    ),
    'firstname'=>array('label'=>'Vorname'),
    'lastname'=>array('label'=>'Nachname'),
    'email'=>array('label'=>'E-Mail')
);
$lang['form_buttons_submit']='Senden';
$lang['form_error_required'] = 'Bitte füllen Sie die erforderlichen Felder aus';

The Form Declaration

Within the declaration-file all fields will be defined. To define a field you must set the following array:

$form[FIELDNAME]=array(
   'type'=>FIELDTYPE,
   'rules'=>RULES,
   'errorchain'=>CHAIN,
   'options'=>OPTIONS,
   'layout'=>LAYOUT
);

1. FIELDNAME: Unique name of element. Do not use "error_required", "error_message", "submit" or "reset".

2. FIELDTYPE: Type of the field like “text”, “dropdown”, “checkbox” etc. (see below).

3. RULES: Validation rules (Like the CI built-in rules plus many more)

4. ERRORCHAIN (Optional): You can set here other fieldnames, separates by colons (|). If the field returns an error, these fields in this list will be invalid, too. They will be outputted with an error-style-class.

5. OPTIONS: Array of options for the types “checkbox”, “radio”, “dropdown”, “multiselect” or “list”. Please remember, here you define only the keys. You can define the language-specific labels of the options in the form-language-file.

Please remember, that the keys that are integers, or strings with a standard representation of an integer, a zero (0) will be prefixed automatically. So if you define the options like array(1,2,3,4) they will be internally converted in array('01, '02', '03', '04').

You do not have to set a dummy-option like “Please select”. This will be done automaticly for you. The text of this option you can set in the form-language-file (the hint-parameter).

To define all the countries you can use the helper-function form_list_countries().

A validation, if only one of this options was submitted to the server will be automatically done. If someone try to submit another option as here defined the error-message of the rule check_valid_options will be thrown.

6. LAYOUT: Here you can set some layout-option for specific field-types: a. checkbox and radio: Number of columns for the types “checkbox”, “radio”. This will set a special style to the element. The default-behavior is to add the style "width:X%;float:left" (X is 100/number of columns). See the description of the global configuration parameter “forms_option_columns_pattern”, too. b. textarea, list and multiselect: Number of rows.

Possible Field Types

If you define the fields you can use the following field types

• text: Will create a text-input field.
• dropdown: Single selectable dropdown field.
• list: Single selectable list.
• multiselect: Multiple selectable list.
• radio: Group of radio-buttons. Every radio-button label is automatically clickable.
• textarea: Textaerea field.
• hidden: Hidden form field.
• password: A password field. Previous input will not be remembered.
• upload: An upload field.
• checkbox: A group of checkboxes. Every checkbox label is automatically clickable.
• calculated: See below.

Rules

Included CI Rules: http://www.codeigniter.com/user_guide/libraries/form_validation.html#rule-reference

The Form Language File

To define the labels of the fields you have to set this array:

$lang[FIELDNAME]	= array(
'label'=>LABEL,
'hint'=>HINT,
'options'=>OPTIONLABELS,
'default'=>DEFAULT,
'error‘=>ERROR
);

Every field can be configured by an array. In this array you can define:

• LABEL: The Label of the field

• HINT: The hint text. Will be used as “title” in every field. In the field-type “dropdown” it will be used for the text of the dummy-option “Please select”.

• OPTIONLABELS: An associative array with the names of the options for a “checkbox”, “dropdown”, “multiselect” and “list”. The keys of the array elements are the option-names.

Every element with a key, not defined in the configuration of this field, will be discarded.

Please remember, that the keys that are integers, or strings with a standard representation of an integer, a zero (0) will be prefixed automatically. So if you define the options like array(1=>'one',2=>'two',3=>'three',4=>'four') they will be internally converted in array('01=>'one', '02'=>'two', '03'=>'three', '04'=>'four').

• DEFAULT: The default value.

• ERROR (Optional): See the caption “field specific error messages”

Embedding the Form in a View

• form_start($form): Start the form. You have to give the form name. A corresponding configuration file of the form must exist. You do not have to think about if you should start a multipart form or not. This will be automatically decided.
• form_field($name): Will output a form-field. You can use this method independent of the type of a field. You can set a second parameter form_field($name,$layout) to set the layout of a field. This will overwrite the layout-definition of the field set in the configuration file (see above).
• form_label ($name): Will output a label of a form-field. To use the original CI-function, you can call CI_form_label.
• form_reset(): Will output a graphical reset-button. The framework function link_button will be used. To use the original CI-function, you can call CI_form_reset.
• form_submit(): Will output a graphical submit-button. The framework function link_button will be used. To use the original CI-function, you can call CI_form_submit.
• form_end(): Ends the form.
• form_errors($field=): Output an error message of the last submitted form. Can be used everywhere in the page. Must not be inwith “form_start” and “form_end”. Optionally you can use the argum ent $field, to get only the error message from one specific field. Otherwise you get all errors of the form.
• form_confirmation(): Output an confirmation message of the last submitted form. Can be used everywhere in the page. Must not be inwith “form_start” and “form_end”.
• form_submitted_name(): The name of the form submitted last.
• form_submitted_incorrect(): Returns TRUE if the last form submission was invalid. You can use the name of the form as parameter form_submitted_ incorrect($name), if you want to check a specific form.
• form_submitted_successful(): Returns TRUE if the last form submission was valid. You can use the name of the form as parameter form_submitted_successful($name), if you want to check a specific form.