Form Helper (*) > - IP.Board (IPB) News
Kanał Rss Kanał Rss
Kanał Atom Kanał Atom

Form Helper (*)

wersja drukowalna wersja Microsoft Word wersja HTML

IPS Community Suite has a powerful Form helper class allowing developers to create forms easily, with automatic validation and security. Forms can include file uploads, can be tabbed, are HTML5 ready and have lots of other features. If you are asking for user-input, you should always use the form helper, never write such functionality manually.

Your form code will usually look something like this:

$form = new IPSHelpersForm;

$form->add( ... );
$form->add( ... );

if ( $values = $form->values() )
	// Form submitted

IPSOutput::i()->output = $form;


Adding form elements

Adding an element a form is done by the $form->add() method. You pass it an object of the element you want - for example, to add a text input to your form, you can do:

$form->add( new IPSHelpersFormText('name') );

Some of the classes available are:

The constructor for all of these classes is:

	 * Constructor
	 * @param	string			$name					Name
	 * @param	mixed			$defaultValue			Default value
	 * @param	bool|NULL		$required				Required? (NULL for not required, but appears to be so)
	 * @param	array			$options				Type-specific options
	 * @param	callback		$customValidationCode	Custom validation code
	 * @param	string			$prefix					HTML to show before input field
	 * @param	string			$suffix					HTML to show after input field
	 * @param	string			$id						The ID to add to the row
	 * @return	void
	public function __construct( $name, $defaultValue=NULL, $required=FALSE, $options=array(), $customValidationCode=NULL, $prefix=NULL, $suffix=NULL, $id=NULL )

For all of the available classes, look at the files in the system/Helpers/Form/ directory. The values acceptable for $options are documented in the source code for each. Be aware that some extend others (for example CheckboxSet extends Select, and has the same $options).

For example, to create a multi-select box you would do something like:

$form->add( new IPSHelpersFormSelect( 'my_select_box', NULL, TRUE, array( 'options' => array( 0 => 'Foo', 1 => 'Bar', 2=> 'Baz' ), 'multiple' => TRUE ) );

Some classes, due to their complexity have further documentation available:


Labels and Descriptions

The $name property, in addition to being the name used for the HTML field, is also used for the label to display. The form helper will automatically look for a language string with the same key to use as the label.

It will also look for a language string appended with "_desc" for the description. For example, if the $name for your field is "my_field", it will use the language string "my_field_desc" as the description. If a language string with that key doesn't exist, no description will be used.

It will also look for a language string appended with "_warning" for a warning block (again if it doesn't exist none is shown). This is normally only ever used with toggles (see below) for example to display a warning when the user selects a particularly dangerous option.



Most classes will provide automatic validation, and their $options provide ways of customising this. For example, if you create an IPSHelpersFormNumber element - it will automatically check if the value is a number, and you can use $options to control the maximum and minimum along with the number of allowed decimal points. The system will automatically display the form again with an inline error message if any of the elements don't validate with no extra code required from you. If however, you want to include custom validation, you can do this with the $customValidationCode property - you simply provide a callback method which throws a DomainException if there's an error. For example, if you wanted a number field where the number 7 is specifically not allowed you could do this like so:

$form->add( new IPSHelpersFormNumber( 'my_field', NULL, TRUE, array(), function( $val )
	if ( $val == 7 )
		throw new DomainException('form_bad_value');
} ) );



Some fields like radios, select boxes and yes/no fields provide a feature called "toggles" which allow you to show or hide other elements depending on the selected value. For example, you might have a yes/no field to turn a feature on, and only when it is set to "yes" do other settings related to it show.

The options available for this depends on the field type. For example, YesNo has two options: togglesOn (which controls which elements to show when the setting is set to "Yes") and togglesOff (which controls which elements to show when the setting is set to "No"). Select has one toggles option which accepts an array, specifying which elements should show for each of the available values. Number has an unlimitedToggles which specifies which elements show when the "Unlimited" checkbox is checked and a unlimitedToggleOn option to reverse that behaviour to when the checkbox is unchecked. For more information, see the source code for each element type.

All of these options accept the HTML ID for what they should show/hide. To make other form elements show/hide you will need to provide IDs for them in the constructor. For example, this form has a YesNo field which when set to "Yes" shows a text input field:

$form->add( new IPSHelpersFormYesNo( 'yes_no_field', NULL, TRUE, array( 'togglesOn' => array( 'text_field_container' ) ) ) );
$form->add( new IPSHelpersFormText( 'text_field', NULL, TRUE, array(), NULL, NULL, NULL, 'text_field_container' ) );


Handling Submissions

When your form is submitted $form->values() will return an array with the values of each element (if the form has not been submitted or validation fails, it returns FALSE).

The value returned for each element depends on the type, and sometimes the options. For example, an IPSHelpersFormText element always returns a string as it's value. However, IPSHelpersFormNumber might return an integer or a float. IPSHelpersFormUpload, on the other hand, returns an IPSFile object (or even an array of them if it's a multiple file upload field).


If you prefer to only receive string values (for example, you want to save the values as a JSON object), you can pass TRUE to the $form->values() method.


Tabs, Headers and Separators

The IPSHelpersForm object provides a number of other methods to create tabbed forms, include headers, etc. For example:

$form->add( new IPSHelpersFormYesNo( 'yes_no_field' ) );
$form->add( new IPSHelpersFormText( 'text_field' ) );
$form->add( new IPSHelpersFormText( 'another_text_field' ) );
$form->add( new IPSHelpersFormSelect( 'select_field', NULL, FALSE, array( 'options' => array( 0, 1, 2, 3 ) ) ) );

For more information on the available methods, see the phpDocs in IPSHelpersForm.


Custom Display HTML

Casting the $form object to a string returns the HTML to display the form. By default, the form is "horizontal". To use "vertical", or to apply any other classes to the form, you can do:

$form->class = 'ipsForm_vertical';

For further customisation, you can call $form->customTemplate() passing a callback with a template to use. This allows you to totally customise the look of the form.

A common use of this is to use a template that looks better in modals:

IPSOutput::i()->output = $form->customTemplate( array( call_user_func_array( array( IPSTheme::i(), 'getTemplate' ), array( 'forms', 'core' ) ), 'popupTemplate' ) );

If you want to create a custom template, you could use the popupTemplate as an example.


Advice and Best Practices

Forms make up a large portion of the UI within the IPS Community. It is important to remember to present a UI that is consistent with other areas of the suite. To this end, we recommend the following best practices:

czw, 01 wrzesień 2016