The Complete Guide to Social Engine 4 Module Development Part 7: Forms and Form Elements
SE4 Forms
I initially intended to make a post about tasks and jobs as part 7 of this series. After working on a number of projects in the months that passed I realized that I forgot to discuss the most common task in SE4 (it’s called SE PHP now but I’ll still refer to it as SE4 if you don’t mind) customization which is customizing forms and creating forms.
In SE4 there are “standard forms” and “custom fields form”. Take for example when in the sign up process, assuming the default order that comes with SE4 out of the box, you are first greeted with a form entitled “Create Account”. This form is an instance of User_Form_Signup_Account which is an instance of Engine_Form. This is the most most common form you'll encounter in SE4 and the subject of this post. The next form in the sign up process asks for your profile details. This is an instance of User_Form_Signup_Fields. Among other things, the elements of this type of form can be customized via the admin panel. These types of form extends Fields_Form_Standard. Most 3rd party modules have this type of form to provide a way for site admins to customize the information to be asked from users pertaining to a particular item. This is a complex and interesting subject matter which is best discused in another post.
Creating Forms
In a module, scripts providing class definitions for forms are located in application/modules/<Modulename>/Form. In our Car module example we need a creation form. So we create the file application/modules/Car/Form/Create.php and it it we put:
The Engine_Form class supports setDescription and setTitle to set the description and title of the form respectively. You can consult the documentation for Zend_Form for a complete list of supported methods.
In the body of init() is where we define the elements of the form. The easiest way to add an element is via this snippet:
Out of the box SE4 (4.5.0) supports the following types:
- Birthdate — renders as 3 select fields for month, day and year. Extends the Date element and includes validation of birthdates i.e inclusion of month/date.
- Button — standard button form field.
- CalendarDateTime — calendar date picker
- Cancel — a form button by default. Can be rendered as a link by setting the option “link”.
- Captcha — renders a captcha. Requires some configuration.
- Checkbox — a standard checkbox.
- Date — renders as 3 select fields for month, day and year
- Dummy
- Duration
- Exception
- FancyUpload
- File
- Float
- Hash
- Heading
- Hidden
- Image
- Integer
- MultiCheckbox
- Multiselect
- MultiText
- Password
- Radio
- Reset
- Select
- SingleRadio
- SubForm
- Submit
- Text
- Textarea
- TinyMce
To specify an element type you may use lower case letters but be careful with multi word names. For example, “multiselect" works as well as "Multiselect" but not "multiSelect". In addition, "TinyMce" and "tinyMce" works but not "tinymce".
The name of the element is required. The name will be the id and name attribute of the rendred form element on the page. These can be overridden by using the element's setAttrib method.
By extending Engine_Form form classes gets the default decorators and thus the same stying as default SE4 forms.
The options parameter sets the attributes of the element or it's options. HTML attributes may be specified as key/value pairs in the options parameter array as in the following example:
The most commonly used options are label, description, and required. Label is the label of the element. Any html code in the value of label are escaped. Unlike label, description can render html code. This is done by setting escaping to false as shown in the example above.
For select, Multiselect, MultiCheckbox, and radio the option multiOptions is used to set the options of the element. This can be an numerically indexed array or an associative array. The keys/indexes will be used as the value of the option elements and the values will be used as the label of the option elements. These elements includes the InArray validator by default. If you dynamically load the options via javascript this can be problematic. To disable it use the option registerInArrayValidator to false.
For button, cancel, reset, cancel and submit the label is used as the label of the button and the label decorator is disabled. For buttons to be grouped and styled properly a display group is used in addition to overriding the default decorators. Please note that although reset and submit are available they are instances of Zend_Form_Element_Submit and Zend_Form_Element_Reset respectively and thus are not styled properly. You may use button for this and set type to "submit" or "reset" to emulate the function. The cancel element is a custom SE4 form element is used very often. By default it is a button which has an onclick attribute which sends the browser back to the previous page. Setting "link" to true will render an anchor tag. As an anchor you may use the "href" option to send the browser to the specified location. The "prependText" is the text prepended to the element (often " or ").
The "decorator", "validators" and "filters" options are discussed in the zend manual.
Creating Custom Elements
In the example above we added the custom element color. The example also shows two ways to specify elements to be added to the form. Here is the class declaration of our color element located in application/modules/Car/Form/Element/Color.php:
The view helper FormColor does the most of the magic here. Here is the code located in application/modules/Car/View/Helper/FormColor.php :
Most of the time creating a custom form elements involves just changing how it is rendered via a view helper which is specified by the $helper property of the element. In this example render a text element in addition to some inline javascript code to create the color picker. Additional styles would be needed for the color picker to display properly.
View helpers can be a subject of a another post. But for now it should be noted that for our FormColor view helper to be available to the framework, the following code must be added to the bootstrap file application/modules/Car/Bootstrap.php:
Using Forms
In a controller action the form should be instantiated and assigned to to view. To populate a form with values use the populate method. Submitted form values are validated via the isValid. This method has the effect of populating the form with filtered values and setting error messages for the form or form elements if any. Use the getValues method to get the filtered values from the form after a successful validation.
Rendering Forms
The following is the content of the view script for the create action for the index controller of the Car module:
The partial contains javascript code to control the tags field’s auto suggest feature. It will be used on both the create and edit routines of the car module and will probably be used in other view scripts for albums, videos etc so it’s logical to put it on a separate script for easy reuse. The following shows it’s content:
Advanced Stuff
You probably read this post wanting to learn how to do stuff like customizing the layout of form, adding sub-forms or creating multi page forms. Unfortunately these are lengthy topics and are discussed else where on the web. Ask Mr. Google and build upon the stuff you just read and you’ll be on your way.
This completes Part 7 of our series. Up next are custom profile fields.
Originally published in https://social-engine-tutorials.blogsplot.com.
