Forms Builder

From CTRNet Wiki
Jump to: navigation, search

Forms Helper Documentation

This is documentation on the usage of the Forms Helper, a custom Component/Helper set used by ATiM to generate display and editing screens. Usage of the Forms Helper will ensure a consistent look and feel to all ATiM screens, and make the application easier for end users.

This documentation assumes you already have a working knowledge of the CakePHP framework and the Advanced Tissue Management(ATiM) web application.

For more information on ATiM, contact CTRNet. For more support or documentation, contact Visual Lizard Inc.


Contents

Form Types

The standard Build Form function call looks like the following... 

 build( $settings, $model, $form, $links, $lang, $paging, $override, $extras );

$settings - Variable used to define some overall settings for the generated Form. The main setting is the type of form being generated. Valid types of forms are:

  • index - Sometimes referred to as the “table” view, the “list” view, or the “listall” view.
  • detail
  • add
  • edit
  • search
  • radiolist
  • checklist
  • datagrid
  • summary - A very specific function that returns dorm data in the format required to create the summary tab that appears in tab menus.

The $settings variable can be either a string or an array. If it's passed as a string, the string value must be one of the valid form types listed above. If it's passed as an array, the first array value must be one of the valid form types listed above. There are some other form settings that can be passed, but they can only be passed as values in the array format. Not all the settings work for all the form types, but here are some examples of available settings:

  • allfields - Ignores the use of the form_fields “flag” values and uses all the fields linked to a particular Form.
  • return - Instead of immediately echoing out the generated form, the form is returned as a string value, and can be saved from the build function to a variable.


$model

The row(s) of Model data that will populate the Form Type. Passed as an array, is standard CakePHP data array format.


$form

An array that details the exact Form to render, the Fields to use in that Form, the way to display each Field Element or Value, etc. The information for this array comes from the Forms Component, and is gathered from the Forms Model, the Forms_Fields Model, the Global_Lookups Model, and more.

In a Controller, the $form array is set like this: 

 $this->set( 'form_variable, $this->Forms->getFormArray('form_alias') );

Where form_variable is whatever your array's variable name will be in the Controller's View, and form_alias is whatever the alias of your Form is in the Forms Model.

$links

An array of keys and values that tell the Forms Helper what links to place on the render Form, where to put them, and how many to put. Each of the array's keys are the names of the Link, and the corresponding values are the URLs for the Link. The keys/names of the links can be anything the developer wants. However, most Form Types parse the array for specific keys and treat them differently.

  • index - All Links will be generated for each row in the rendered table. The only exception is for a link with the key of “add”, which will be placed under the table in the Action bar.
  • detail - All Links generated under the Form, in the Action bar.
  • add - All Links generated under the Form, in the Action bar, except for a Link with the key “add”. That URL value will be used as the Form's action attribute in the Form tag.
  • edit - All Links generated under the Form, in the Action bar, except for a Link with the key “edit”. That URL value will be used as the Form's action attribute in the Form tag.
  • search - All Links generated under the Form, in the Action bar, except for a Link with the key “search”. That URL value will be used as the Form's action attribute in the Form tag.
  • radiolist - All Links will be generated for each row in the rendered table. The only exception is for a link with the key of “radiolist”, which is not used as a Link at all; it is the name attribute of the rendered radio Form Element for each Checklist item/row.
  • checklist - All Links will be generated for each row in the rendered table. The only exception is for a link with the key of “checklist”, which is not used as a Link at all; it is the name attribute of the rendered checkbox Form Element for each Checklist item/row. All array keys/values that are rendered as Links are given an icon, and each of the word(s) in the keys have their first letter capitalized. The icon chosen is based on the first word of the key. For instance, if the key of the first array value is “add” or “add new item” or “add another”, that link will get the add icon. If the Forms Helper cannot make an exact match, it will make a best guess based on the first world of the key. For instance, if the key is “create a sample” or “new item”, that Link will get the add icon.

Links icons

It is possible to override the default icon used by a link. When you define your link, rather than having the value being the link itself, define it as an array where you will define the "link" key as the link and the "icon" key as the icon/css class of the icon you want.

Note that you should use 16x16px icons.


$lang

An array set by the main CTRApp application, holding the list of aliases and translations. This array is used by the Forms Helper to translate labels, tags, pulldown options, etc.

$paging

This variable is optional. Set in the corresponding Controller using the Pagination Component/Helper. It is used only on index Form Types, to provide pagination links at the bottom of the rendered table.

$override

This variable is optional. An array of items used to override the default values used in specific Form Elements. The keys are used to identify the Form Element to be overridden (using the Model and Field names) and the value is what is used. The effect is different for each Form Element, and will be covered below.

$extras

This variable is optional. It can be either a string or an array, and is used to attach HTML to the rendered Form. If it is passed as a string, the HTML is rendered at the end of the Form. If an array, the developer can use the array keys “start” and/or “end”, depending on where they what the HTML to appear. The HTML passed through the $extras variable is not checked or parsed in any way, and is tacked onto the Form blindly by the Forms Helper.

Form Elements

Every Type of Form is build from individual Form Elements. Form Elements are the fields of data, types of data, and types of input fields that each Form is made up from. Each Form must have at least one Form Element. Form Elements are defined in the Form_Fields Model, and are linked to the Forms Model. Most Form Elements have to “modes”; a display mode and an edit mode. The display mode is when the data for that Element is simply displayed to screen, with perhaps only a Lookup or Translation happening. It is static, and it is used in the Form Types like index, detail, etc. The edit mode is used in the add, edit, and search Form Type, and defines how that data is entered, edited, and manipulated. It is usually HTML form fields and input fields. Here are the different Form Elements a developer has available through the Forms Helper:

input

A standard HTML form input field, the data entered is saved directly to the Model. No translation is made.

textarea

A standard HTML form textarea field, the data entered is saved directly to the Model. No translation is made.

password

A standard HTML form password field, the data entered is saved directly to the Model. No translation is made. Displayed normally in display mode, but in edit form, the data entered cannot be read, being replaced with asterisk or bullets (depending on the browser).

hidden

Displays normally, but in add/edit mode, renders as a standard HTML hidden form field. The field "cannot" be edited by the user. It is used by the developer to change data in the Model based on the Form submission.

number

In display and edit mode, works exactly like the input field. A standard HTML input field, whose data is saved directly to the Model. Meant specifically for numbers, and when used in the search Form Type, renders as two input fields so users can search for a number by way of a range.

The number field type includes subtypes that will, as an additional feature, be automatically validated by the application when in edit mode.

integer

Validates if the entered value is an integer.

integer_positive

Validates if the entered value is a positive integer.

float

Validates if the entered value is a float.

float_positive

Validates if the entered value is a positive float.

date

Used with date datatable fields, used to enter, edit, and display date values. In display mode, renders the date in an order defined by the user preferences. The month name will be in text and is translated using the $lang variable. In edit mode, the date field is automatically broken up into three inputs. The user chooses each portion. The data is put back together into a single field value in the Controller's beforeFilter() Action using the cleanupFields() function. This Form Element appears twice in search Form Type, allowing users to search over a range of dates.

WARNING: Using datetime as datatable field will cause validation to fail.

time

Works exactly like the above date Form Element, but for time instead. Used with datetime datatable fields, used to enter, edit, and display time values. In display mode, renders the date using the hour and minutes. In edit mode, the time field is automatically broken up into inputs. The user chooses each portion. The data is put back together into a single field value in the Controller's beforeFilter() Action using the cleanupFields() function. This Form Element appears twice in search Form Type, allowing users to search over a range of time.

datetime

Works exactly like the above date and time Form Element, put together. Used with datetime datatable fields, used to enter, edit, and display time values.

WARNING: Using date as datatable field will cause validation to fail.

select

In edit mode, creates a dropdown with options populated from the linked Global Lookups Model. If the Form Element has no validation linked to it through the Form_Validations Model, a blank option will be included as the first option. The setting dropdown_options can be passed on this Form Element in the format of an array. If passed correctly, that array will be used for the pulldown's options instead of the Global Lookup values. The array's keys will be used as the submitted values and the array's values will be used as the options. No translation will be made on the provided array.

radiolist

In edit mode, creates a list of radio buttons with options populated from the linked Global Lookups Model. If the Form Element has no validation linked to it through the Form_Validations Model, a blank option will be included as the first option. The setting dropdown_options can be passed on this Form Element in the format of an array. If passed correctly, that array will be used for the radio buttons instead of the Global Lookup values. The array's keys will be used as the submitted values and the array's values will be used as the options. No translation will be made on the provided array.

checklist

In edit mode, creates a list of checkboxes with options populated from the linked Global Lookups Model. The setting dropdown_options can be passed on this Form Element in the format of an array. If passed correctly, that array will be used for the checkboxes instead of the Global Lookup values. The array's keys will be used as the submitted values and the array's values will be used as the options. No translation will be made on the provided array.

autocomplete

The autocomplete fields are text inputs that, as soon as the user starts typing into them, will give suggestions based on what has been typed so far.

Special element

Retrieved from "http://www.ctrnet.ca/mediawiki/index.php/Forms_Builder"
Personal tools