[IPS The Development Channel] 4.0 - Forms

[NewsBot]

Forms are an ubiquitous aspect of any web application. In the IPS Social Suite, particularly in the Admin CP, I often find myself copying and pasting code in various places to create a form. We've had the ipsRegistry::getClass('output')->formInput() and similar methods since 3.0, but you still have to copy all the HTML to display the rows, and write all the code to validate it yourself.

 

Copying and pasting code is something all developers hate. It's a red flag that you're probably doing something wrong. In IPS 4.0, we've written a central form building helper class to alleviate this.

 

Just as a reminder: Everything in this blog is a work in progress - naturally someone with a much keener design sense than I will be going over the interface - I'm just demonstrating the functionality, not a finished product 

 

 

The Basics

 

Let's say I want to create a form with a single text input field. I simply initiate the form, add an object representing the input, and then display the form (it has a __toString method) - like so:

 

The helper will automatically look for language strings with the same name as the form element and use them. If there is a language string with the same name and then "_desc" - it'll use that as the description.

 

So the above code, in the ACP, produces something like this:

 

 

Required

 

Let's say I want the field to be required - I just pass a third argument indicating so. When the form is submitted, if no value has been provided, it will automatically display an inline error:

 

new IPSHelpersFormText( 'name', '', TRUE, array( 'minLength' => 5 ) )

 

 

 

For a number field, I might specify the number of decimal points to round to, which it will do on the fly:

 

Watch Video

 

 

Or I could add an "Unlimited" checkbox, which is quite common for Admin CP settings:

 

 

 

Custom Validation

 

If the built-in options don't provide enough validation for a given need, you can pass a lambda function as a 5th argument:

 

new IPSHelpersFormUpload( 'name', NULL, FALSE, array( 'multiple' => TRUE ) )

 

$form = new IPSHelpersForm();$form->add( ... );if ( $values = $form->values() ){ // $values contains the values from the form}else{ IPSOutput::i()->output .= $form;}

 

 

The values will be returned in a way that is appropriate to the input type. For example, a text input field will return a string, number input will return either an integer or float, an upload field will return an