Skocz do zawartości
  • Zarejestruj się
Zaloguj się, aby obserwować

[Dokumentacja IPS4] Form Helper (*)

Polecane posty

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 \IPS\Helpers\Form;

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

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

\IPS\Output::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 \IPS\Helpers\Form\Text('name') );

Some of the classes available are:

  • \IPS\Helpers\Form\Text for normal text input
  • \IPS\Helpers\Form\Editor for WYSIWG text input
  • \IPS\Helpers\Form\Upload for file uploads
  • \IPS\Helpers\Form\Date for dates
  • \IPS\Helpers\Form\Select for a select box
  • \IPS\Helpers\Form\YesNo for yes/no radio buttons

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 \IPS\Helpers\Form\Select( '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 \IPS\Helpers\Form\Number 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 \IPS\Helpers\Form\Number( '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 \IPS\Helpers\Form\YesNo( 'yes_no_field', NULL, TRUE, array( 'togglesOn' => array( 'text_field_container' ) ) ) );
$form->add( new \IPS\Helpers\Form\Text( '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 \IPS\Helpers\Form\Text element always returns a string as it's value. However, \IPS\Helpers\Form\Number might return an integer or a float. \IPS\Helpers\Form\Upload, on the other hand, returns an \IPS\File 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 \IPS\Helpers\Form object provides a number of other methods to create tabbed forms, include headers, etc. For example:

$form->add( new \IPS\Helpers\Form\YesNo( 'yes_no_field' ) );
$form->add( new \IPS\Helpers\Form\Text( 'text_field' ) );
$form->add( new \IPS\Helpers\Form\Text( 'another_text_field' ) );
$form->add( new \IPS\Helpers\Form\Select( 'select_field', NULL, FALSE, array( 'options' => array( 0, 1, 2, 3 ) ) ) );

For more information on the available methods, see the phpDocs in \IPS\Helpers\Form.


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:

\IPS\Output::i()->output = $form->customTemplate( array( call_user_func_array( array( \IPS\Theme::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:

  • Always phrase settings in the positive. For example, say "Enable feature?", don't say "Disable feature?". "Yes" should always mean something is "On".
  • Make labels short and concise and use descriptions only if necessary. For example, don't have a field where the label is "Enable feature?" and the description is "Set this to yes to enable the feature" - that description isn't necessary.
  • Use prefixes and suffixes rather than adding information to the label or description where possible. For example, don't have a label that says "Number of days before deleting" - make the label "Delete after" and the suffix that appears after the field say "days".
  • Never refer to other settings in labels or descriptions. For example, do not have a description that says "Only applies if the above setting is on". Use toggles to indicate this to the user.
  • Never make entering a particular value do something special. For example, do not have a description that says "Leave blank for unlimited" - use an unlimited checkbox or a separate setting which toggles other settings.

Wyświetl pełny artykuł

Udostępnij ten post

Link to postu
Udostępnij na innych stronach

Dołącz do rozmowy

Możesz pisać i zarejestrować się później. Jeśli masz konto,Zaloguj się teraz, aby publikować na swoim koncie.


×   Wklejony jako tekst z formatowaniem.   Wklej jako zwykły tekst

  Dozwolonych jest tylko 75 emoji.

×   Twój link będzie automatycznie osadzony.   Wyświetlać jako link

×   Twoja poprzednia zawartość została przywrócona.   Wyczyść edytor

×   Nie możesz wkleić zdjęć bezpośrednio. Prześlij lub wstaw obrazy z adresu URL.

Zaloguj się, aby obserwować  

  • Kto przegląda   0 użytkowników

    Brak zalogowanych użytkowników przeglądających tę stronę.

  • Utwórz nowe...

Ważne informacje

W celu świadczenie usług przez nasz Serwis na najwyższym poziomie, w ramach Serwisu wykorzystujemy pliki Cookies (tzw. ciasteczka). Korzystając ze stron Serwisu IPSBEYOND.PL bez zmiany ustawień przeglądarki będą one zapisane w pamięci urządzenia. Jeżeli nie dokonacie Państwo zmiany ustawień przeglądarki internetowej to wyrażacie zgodę na zapisywanie plików Cookies.