Jump to content


  • We are moving our Documentation to our new Guides area.

    As articles are moved they will be deleted. Please start following the new guides. We look forward to publishing all our new guides soon!

  • Form Helper (*)

    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.

    User Feedback

    Recommended Comments

    A few examples to load Nodes (forums, groups, downloads or gallery categories, themes, etc.):


        $form->add( new \IPS\Helpers\Form\Node( 'setting_name', \IPS\Settings::i()->
    setting_name ? \IPS\Settings::i()->setting_name : 0, FALSE, array( 'class' => 'IPS\forums\Forum', 'zeroVal' => 'use_cat_forum' ), NULL, NULL, NULL, 'setting_name' ) );

    The important here is the 'class' => 'IPS\forums\Forum'. You can use other elements:

    'class' => '\IPS\Theme'
    'class' => 'IPS\Application'
    'class' => 'IPS\gallery\Album'
    'class' => 'IPS\gallery\Category'
    'class' => 'IPS\downloads\Category'


    Link to comment
    Share on other sites

    1. This is just a hopeful suggestion but as you explained how to create custom form templates, how would we go about adding custom css to target that template ?

    2. When adding a custom template, the default url points to the applications directory. How can I make it point to the plugins?

    Edited by Tom Christian
    Link to comment
    Share on other sites

    There's also the textarea type: \IPS\Helpers\Form\TextArea

        $form->add( new \IPS\Helpers\Form\TextArea( 'admin_notes', ( isset( \IPS\Data\Store::i()->admin_notes ) ) ? htmlspecialchars( \IPS\Data\Store::i()->admin_notes, \IPS\HTMLENTITIES, 'UTF-8', FALSE ) : '' ) );


    Link to comment
    Share on other sites

    Looked at a few forms but don't see how to add the action url, how does this work ?

    ​Forms submit back to the page they are created on. See the first code example in this article, which indicates where you put the code to run on submission.

    Link to comment
    Share on other sites

  • Create New...

Important Information

We use technologies, such as cookies, to customise content and advertising, to provide social media features and to analyse traffic to the site. We also share information about your use of our site with our trusted social media, advertising and analytics partners. See more about cookies and our Privacy Policy