<field
name="email2"
type="text"
id="email2"
label="PROFILE FORM EMAIL2 LABEL"
description="PROFILE FORM EMAIL2 LABEL"
message="PROFILE FORM EMAIL2 MESSAGE"
class="inputbox validate-email"
size="30"
default=""
required="true"
filter="string"
validate="equals"
field="email1"
/>
The field definitions could be used in a user data edit screen to ensure that the user's e-mail address is unique to that user and that the email1 and email2 fields match. The email1 field will validate that the e-mail address is unique to the user and the email2 field will verify that it's supplied value matches the value given to email1. You can also specify custom validation messages via the message attribute.
Getting A Form
Let's assume you have an MVC component with a "forms" folder within the "models" folder. In the forms folder, you have a form file named "profile.xml". To get a instance of the form you would do something like:
// Get the form.
jimport('joomla.form.form');
JForm::addFormPath(JPATH_COMPONENT.DS.'models'.DS.'forms');
$form = &JForm::getInstance('jform', 'profile', true, array('array' => true));
JForm::addFormPath() works similarly to JModel::addIncludePath or JHtml::addIncludePath(). JForm::getInstance() returns a JForm instance. The first parameter is a name to identify the form by and will come into play when with the array option that you see in the forth parameter. The second parameter, "profile", tells JForm where to get the XML data from and the third option indicates that "profile" is a file name. Instead of specifying a file name, you can pass in straight XML into the second parameter and set the third parameter to false. The fourth parameter, array('array' => true), tells JForm to render the individual field names as an array. If our profile.xml contained the fields posted above, the field names would be jform[id], jform[email1], and jform[email2]. If the array option is set to false, the field names would be rendered as id, email1, and email2.
The array option is very convenient because it makes loading the form data and running it through the filter/validator extremely quick.
// Get the form.
jimport('joomla.form.form');
JForm::addFormPath(JPATH_COMPONENT.DS.'models'.DS.'forms');
$form = &JForm::getInstance('jform', 'profile', true, array('array' => true));
// Get the profile data.
$data = JRequest::getVar('jform', array(), 'post', 'array');
// Filter and validate the form data.
$data = $form->filter($data);
$return = $form->validate($data);
// Check for errors and save...
Notes
* We are still sorting out some of the error handling and validation warning feedback for PHP 5.2. The error handling will probably be updated in the near future to make distinguishing hard errors from validation errors easier.
* The library as a whole is quite powerful and I hope that it is fairly easy to understand but it will probably require some trial and error to really get the hang of. The newly committed com_weblinks admin component should serve as a useful example of how to use the new form package and the access control system will begin to use it more in the near future.
That is all I can think of right now but I'm sure I've probably forgot something. If you guys have any questions, feel free to ask and I will do my best to help you out.
Best,
Rob Schley