Joomla! Documentation - User contributions [en]

Client-side form validation

2017-11-02T14:06:42Z

Tonypartridge: JUtility GetToken was deprecated.

{{JSplit}}
==Introduction==

Joomla 1.5 and later versions contain a behavior, which allows your form and its elements to be validated at client side, i.e., before it is submitted to the server. The behavior enables the script '''validate.js''' and used [http://mootools.net MooTools] up to version 3.2 and jQuery from version 3.3.

Note: Validate.js is a validation system different from the one provided by [http://mootools.net/docs/more/Forms/Form.Validator MooTools].

==Enable the Validation==

Add a behavior to your form view template. For Joomla versions before 1.5.2:
<source lang="php">
JHtmlBehavior::formvalidation();
</source>
For versions from 1.5.2 to 3.3.6:
<source lang="php">
JHtml::_('behavior.formvalidation');
</source>
For versions from 3.4:
<source lang="php">
JHtml::_('behavior.formvalidator');
</source>

Add the form-validate class to your form
<source lang="html4strict">
<form class="form-validate"> ... </form>
</source>

Add a validation class to your form field declarations. Joomla adds a ''blur'' handler to validate the form field when the user moves away from the field.
<source lang="xml">
<field name="email" type="text" class="required validate-email" size="30" />

//For radios make sure the class is applied to the options:

<field name="ThisorThat" type="radio" label="Please say if it was full-time or the part-time equivalent?" >
<option value="This" class="required">This</option>
<option value="That" class="required">That</option>
</field>
</source>

For lists which are required the first option should have a value of "" as per:

<source lang="xml">
<field name="selectme" type="list" required="true" label="Please say if it was full-time or the part-time equivalent?" >
<option value="">Please Select</option>
<option value="This">This</option>
<option value="That">That</option>
</field>
</source>

The following classes are available:
* required
* validate-username
* validate-password
* validate-numeric
* validate-email
* validate-[custom] -> custom defined - see below

Note: Joomla 2.5 translates the ''required'' field attribute into a ''required'' class value.

Finally, add the ''validate'' class to your submit button. This will cause an ''onclick'' handler to be added that validates the whole form. The form will only be submitted if it is valid.
<source lang="html4strict">
<button type="submit" class="validate">Submit form</button>
</source>

==Custom Handlers==

If you want a custom handler, you can add one to the class, as in the following example (to be defined AFTER loading validate.js):

MooTools
<source lang="javascript">
window.addEvent('domready', function(){
document.formvalidator.setHandler('birth', function(value) {
regex=/^\d{4}-\d{2}-\d{2}$/;
return regex.test(value);
});
});
</source>
jQuery
<source lang="javascript">
jQuery(document).ready(function(){
document.formvalidator.setHandler('birth', function(value) {
regex=/^\d{4}-\d{2}-\d{2}$/;
return regex.test(value);
});
});
</source>
You can then assign validate-birth to any field to make it validate as yyyy-mm-dd. (Valid date is not checked!)

If you want a custom handler to check both the passwords (Password and Confirm Password) are same, please add the following script after the validate.js:

MooTools
<source lang="javascript">
window.addEvent('domready', function(){
document.formvalidator.setHandler('passverify', function (value) {
return ($('password').value == value);
});
});
</source>

jQuery
<source lang="javascript">
jQuery(document).ready(function(){
document.formvalidator.setHandler('passverify', function (value) {
return (jQuery('input[type=password]').value == value);
});
});
</source>
Add the class "validate-passverify" to the input field as below:
<source lang="html4strict"><input class="inputbox required validate-passverify" type="password" id="password2" name="password2" size="40" value="" />
</source>

==Styling/Templating Invalid Elements==

Joomla assigns the ''invalid'' class to form fields that do not pass the validation test. ''invalid'' is also added to the field labels.
If you style the class in the cascading style sheet, your users will be able to see which fields are wrong. For instance:
<source lang="css">
.invalid {
border-color: red !important;
}
</source>
Some site templates may already contain such definition. (This one is taken from ''beez_20''.)



==Problem & workaround with JToolBar==
If you are using JHTML::_('behavior.formvalidation') with JToolBar, for example use in backend, the above method will not work. This is because it depends on onSubmit event which did not fire when we call form.submit via JavaScript. To work around this, we have to move the code in onSubmit to be in submitbutton function override. This will look like this:-
<source lang="javascript">
<script type="text/javascript">
/* Override joomla.javascript, as form-validation not work with ToolBar */
function submitbutton(pressbutton) {
if (pressbutton == 'cancel') {
submitform(pressbutton);
}else{
var f = document.adminForm;
if (document.formvalidator.isValid(f)) {
f.check.value='<?php echo JSession::getFormToken(); ?>'; //send token
submitform(pressbutton);
}
else {
var msg = new Array();
msg.push('Invalid input, please verify again!');
if ($('title').hasClass('invalid')) {
msg.push('<?php echo JText::_('COM_JONGMAN_ERROR_SCHEDULE_TITLE_IS_REQUIRED')?>');
}
if($('admin_email').hasClass('invalid')){
msg.push('<?php echo JText::_('COM_JONGMAN_ERROR_INVALID_EMAIL')?>');
}
alert (msg.join('\n'));
}
}
}
</script>
</source>

==More on mootools validation==
More available classes on the mootools site here: [http://mootools.net/docs/more/Forms/Form.Validator#Validators http://mootools.net/docs/more/Forms/Form.Validator#Validators]

==Server- or Client-side validation?==
[[Form validation]]

<noinclude>[[Category:Tutorials]][[Category:Development]][[Category:Component Development]]</noinclude>

List form field type

2017-10-09T04:41:55Z

Tonypartridge: Added requires usage to the option field.

<noinclude><languages /></noinclude>
<translate>
The '''list''' form field type provides a drop down list or a list box of custom-defined entries. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.</translate>
[[Image:Params.list.jpg|right]]
<translate>
* '''type''' (mandatory) must be ''list''.</translate>
<translate>
* '''name''' (mandatory) is the unique name of the field.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''default''' (optional) is the default list item value.</translate>
<translate>
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.</translate>
<translate>
* '''class''' (optional) is a CSS class name for the HTML form field. If omitted this will default to 'inputbox'.</translate>
<translate>
* '''multiple''' (optional) is whether multiple items can be selected at the same time (''true'' or ''false'').</translate>
<translate>
* '''required''' (optional) if set to true, the first field option should be empty, see last example.</translate>
* '''useglobal''' (optional) if set to true, it will show the value that is set in the global configuration if found in the database.

<translate>
The XML <code><field></code> element must include one or more <code><option></code> elements which define the list items. The text between the <code><option></code> and <code></option></code> tags is what will be shown in the drop down list and is a translatable string. The <code><option></code> tag takes the following argument:</translate>

<translate>
* '''value''' (mandatory) is the value that will be saved for the field if this item is selected.</translate>
* '''requires''' (optional) Values: multilanguage, associations and adminlanguage can be used..

<translate>
Tip: Don't forget to close the field definition with <code></field></code>.</translate><br />
<translate>
Tip: Add first an option without a value, with a text like "Select an option". Otherwise, in case of a required field, the first option with a value gets silently selected (i.e., without the user choosing it). This text will typically be seen by users before clicking the dropdown list.</translate>

<translate>
Example XML field definition:</translate>
<source lang="xml"><field name="mylistvalue" type="list" default="" label="Select an option" description="">
<option value="0">Option 1</option>
<option value="1">Option 2</option>
</field>
</source>

<translate>
Example XML field definition with required field value:</translate>
<source lang="xml"><field name="mylistvalue" type="list" default="" required="true" label="Select an option" description="">
<option value="">Please Select</option>
<option value="0">Option 1</option>
<option value="1">Option 2</option>
</field>
</source>

<translate>=== See also === </translate>
<translate>

* [[S:MyLanguage/Filelist form field type|Filelist form field type]]
* [[S:MyLanguage/Folderlist form field type|Folderlist form field type]]
* [[S:MyLanguage/Imagelist form field type|Imagelist form field type]]
* [[S:MyLanguage/Standard form field types|List of standard form field types]]
</translate>

<noinclude>
<translate>

[[Category:Standard form field types]]
</translate>
</noinclude>

How to use the filesystem package

2017-08-23T14:18:03Z

Tonypartridge: Space should follow after //

{{version|1.5,2.5,3.x}}
=Using the JFILE:: class=

There are 4 classes in the filesystem library.

* JFile:: (file.php)
* JFolder:: (folder.php)
* JPath:: (path.php)
* JArchive:: (archive.php)

This tutorial focuses on the JFile:: class.

The base for filehandling is the JFile class, found in libraries/joomla/filesystem/file.php
Below you can see the most common options from this library file. At the end of this post you can find a very simple script for file upload.

==Get file extension==
Syntax:
<source lang=php>
$ext = JFile::getExt($filename);
</source>

Pretty clear, just feed the function with a filename and it will return the extension of the file you selected.

==Strip file extension==
Syntax:
<source lang=php>
$name = JFile::stripExt($filename);
</source>
This will return the filename without the extension.

==Clean filename==
Syntax:
<source lang=php>
$safefilename = JFile::makeSafe($filename);
</source>
It cleans out all odd characters from a filename and returns a safe filename.

==Copy a file==
Syntax:
<source lang=php>
JFile::copy($src, $dest);
</source>
It is basically a wrapper for the PHP copy() function, but also checks if the file you want to copy exists and the destination really is available. Great thing is that this function also makes use of the FTP-layer in J15 if necessary.

==Delete a file==
Syntax:
<source lang=php>
JFile::delete($path.$file);
</source>
It tries to delete the file, making sure it is actually existing, but also checks permissions. If permissions are not set up properly, it tries to change them and delete the file. It also uses the FTP-layer when necessary.

==Upload a file==
Syntax:
<source lang=php>
JFile::upload($src, $dest);
</source>
It is basically the wrapper for the PHP move_uploaded_file() function, but also does checks availability and permissions on both source and destination path.

==Example==
So how does that look in a script? I put up a small code snippet of an upload script. Some of the functions are used.
The script is fired from an upload form. That form has a file element, called file_upload (see below).
<source lang=php>
<form name="upload" method="post" enctype="multipart/form-data">
<input type="file" name="file_upload" />
<input type="submit" />
</form>
</source>

Note:
If you didn´t add the part: enctype="multipart/form-data" then you are unable to upload a file!

Upload code looks like this:
<source lang=php>
<?php
/*
* File upload example
*/
// Retrieve file details from uploaded file, sent from upload form
$file = JFactory::getApplication()->input->get('file_upload');

// Import filesystem libraries. Perhaps not necessary, but does not hurt
jimport('joomla.filesystem.file');

// Clean up filename to get rid of strange characters like spaces etc
$filename = JFile::makeSafe($file['name']);

// Set up the source and destination of the file
$src = $file['tmp_name'];
$dest = JPATH_COMPONENT . DS . "uploads" . DS . $filename;

// First check if the file has the right extension, we need jpg only
if (strtolower(JFile::getExt($filename)) == 'jpg')
{
// TODO: Add security checks

if (JFile::upload($src, $dest))
{
// Redirect to a page of your choice
}
else
{
// Redirect and throw an error message
}
}
else
{
// Redirect and notify user file is not right extension
}
?>
</source>

=Using the JFolder:: class=
The base for folder handling is the JFolder class, found in libraries/joomla/filesystem/folder.php
Below I will discuss the most common options from this library file. At the end of this post, I put it together in a very simple script as an exmaple

==Copy folder==
Syntax:
<source lang=php>
JFolder::copy($src, $dest, $path, $force);
</source>
This will copy a complete folder and all of it’s contents to another location on the server. It does permission and availability checking on both source and destination. By using $path you can enter a basepath to prefix to the filename and by setting the $force parameter to true, you can force the overwriting of already existing files. If set in the configuration, the FTP-layer will be used.

==Create folder==
Syntax:
<source lang=php>
JFolder::create($path, $mode);
</source>
This is basically a wrapper for the php mkdir() function, but with error permissions and availability checking. This one also uses the FTP-layer when set in the configuration. $mode will set the default permission, once copied and defaults to 0755.

==Move folder==
Syntax:
<source lang=php>
JFolder::move($src, $dest);
</source>
Basically a wrapper for the php rename() function, but with permissions and availability checking. This one also uses the FTP-layer when set in the configuration.

==Check if folder exists==
Syntax:
<source lang=php>
JFolder::exists($path);
</source>
Wrapper for the php is_dir() function. Pretty straightforward, returns true if folder exists.

==Read files from folder==
Syntax:
<source lang=php>
JFolder::files($path, $filter = '.', $recurse, $fullpath , $exclude);
</source>
Function to read files from a folder. When setting $recurse to true, also subfolders will be searched. $fullpath set to true returns the full path in the array. With $exclude, you can offer an array of extensions, not to include in the search for files. It returns an array with all filenames.

==Read folders from filesystem==
Syntax:
<source lang=php>
JFolder::folders($path, $filter = '.', $recurse, $fullpath , $exclude);
</source>
Exactly the same as JFolder::files(), except this does only return an array with foldernames.

==Make a tree like list from a folder structure==
Syntax:
<source lang=php>
JFolder::listFolderTree($path, $filter, $maxLevel = 3, $level = 0, $parent = 0);
</source>
It will read a folder, specified in $path and will return all folders in an array, suitable for tree display. You can specify the number of levels. The folder array looks like this:
<source lang=php>
Array
(
[0] => Array
(
[id] => 1
[parent] => 0
[name] => administrator
[fullname] => g:/joomla_1012/administrator
[relname] => g:/joomla_1012/administrator
)

[1] => Array
(
[id] => 2
[parent] => 1
[name] => backups
[fullname] => g:/joomla_1012/administrator/backups
[relname] => g:/joomla_1012/administrator/backups
)

[2] => Array
(
[id] => 3
[parent] => 1
[name] => components
[fullname] => g:/joomla_1012/administrator/components
[relname] => g:/joomla_1012/administrator/components
)
)
</source>

==Clean a path string==
Syntax:
<source lang=php>
JFolder::makeSafe($path);
</source>
Identically to the JFile::makeSafe() function. It cleans all odd characters out of the string and returns a clean path.

==Example==
Ok, and how does this look in actual code. We are going to read the contents of a folder called images. In it, al large number of files are placed. We want to create a subfolder, called jpg and filter all jpg files out and move them to the jpg subfolder. After that, we will move the complete subfolder to another place on the server.
<source lang=php>
<?php
// First we set up parameters
$searchpath = JPATH_COMPONENT . '/images';

// Import the folder system library
jimport('joomla.filesystem.folder');

// Then we create the subfolder called jpg
if (!JFolder::create($searchpath . "/jpg"))
{
// Throw error message and stop script
}

// Now we read all jpg files and put them in an array.
$jpgFiles = JFolder::files($searchpath, '.jpg');

// Now we need some stuff from the JFile:: class to move all files into the new folder
foreach ($jpgFiles as $file)
{
JFile::move($searchpath . '/' . $file, $searchpath . '/' . 'jpg' . $file);
}

// Lastly, we are moving the complete subdir to the root of the component.
if (JFolder::move($searchpath . '/'. 'jpg', JPATH_COMPONENT))
{
// Redirect with perhaps a happy message
}
else
{
// Throw an error
}
?>
</source>

This is example script only, but gives a general idea of the possibilities.

<noinclude>[[Category:Development]]</noinclude>

Sending email from extensions

2017-01-23T09:25:50Z

Tonypartridge: . $send->__toString() doesn't exist and causes fatal error in J3.6.

{{Joomla version|version=2.5|time=and after}}
This is an example of how to send an email from a Joomla component. You would typically put this into your component's controller.
=== Fetch the Mail Object ===
A reference to the global mail object (JMail) is fetched through the JFactory object. This is the object creating our mail.

<source lang="php">
$mailer = JFactory::getMailer();
</source>

=== Set a Sender ===
The sender of an email is set with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setSender setSender]. The function takes an array with an email address and a name as an argument. We fetch the site's email address and name from the global configuration. These are set in the administration back-end (Global Configuration -> Server -> Mail Settings).

<source lang="php">
$config = JFactory::getConfig();
$sender = array(
$config->get( 'mailfrom' ),
$config->get( 'fromname' )
);

$mailer->setSender($sender);
</source>

In 3.1, $config->getValue() should be changed to $config->get()

=== Recipient ===
You set the recipient of an email with the function [http://api.joomla.org/1.5/Joomla-Framework/Mail/JMail.html# addRecipient].
To set the email address to the currently logged in user, we fetch it from the user object.

<source lang="php">
$user = JFactory::getUser();
$recipient = $user->email;

$mailer->addRecipient($recipient);
</source>

If we had multiple recipients, we would put each recipient's email address in an array.

<source lang="php">
$recipient = array( 'person1@domain.com', 'person2@domain.com', 'person3@domain.com' );

$mailer->addRecipient($recipient);
</source>

=== Create the Mail ===
We need to set a subject line and create the text body. The subject is set with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setSubject setSubject].

The easy way to create an email body is as a string with plain text. Use the function [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setBody setBody] to add a message to the mail body. You can also attach a file with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#addAttachment addAttachment]. It takes a single file name or an array of file names as the argument.

<source lang="php">
$body = "Your body string\nin double quotes if you want to parse the \nnewlines etc";
$mailer->setSubject('Your subject string');
$mailer->setBody($body);
// Optional file attached
$mailer->addAttachment(JPATH_COMPONENT.'/assets/document.pdf');
</source>

If you prefer to format your email in HTML, you need to tell the mailer it is HTML. This is done with [http://api.joomla.org/Unknown/PHPMailer.html#methodIsHTML IsHTML]. When sending HTML emails you should normally set the [http://api.joomla.org/Unknown/PHPMailer.html#$Encoding Encoding] to base64 in order to avoid unwanted characters in the output. The subject line and any attachments are handled as above, with the exception of images embedded in the HTML. These are taken care of with the function [http://api.joomla.org/Unknown/PHPMailer.html#AddEmbeddedImage AddEmbeddedImage].

<source lang="php">
$body = '<h2>Our mail</h2>'
. '<div>A message to our dear readers'
. '<img src="cid:logo_id" alt="logo"/></div>';
$mailer->isHtml(true);
$mailer->Encoding = 'base64';
$mailer->setBody($body);
// Optionally add embedded image
$mailer->AddEmbeddedImage( JPATH_COMPONENT.'/assets/logo128.jpg', 'logo_id', 'logo.jpg', 'base64', 'image/jpeg' );
</source>

Normally you would leave any images on your server and refer to them with an ordinary HTML image tag, to reduce size of the mail and the time sending it.

=== Sending the Mail ===
The mail is sent with the function [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#Send Send]. It returns '''true''' on success or a JError object.

<source lang="php">
$send = $mailer->Send();
if ( $send !== true ) {
echo 'Error sending email: ';
} else {
echo 'Mail sent';
}
</source>

You would probably want to write your own error handler, if there is an error sending the mail.

The JMail object is used for sending mail in Joomla's contact manager. See the file joomla/components/com_contact/controller.php

===See also===
* [http://api.joomla.org/Joomla-Platform/JFactory.html#getMailer JFactory->getMailer on api.joomla.org]

[[Category:Development]]
[[Category:Component Development]]

Sending email from extensions

2017-01-20T15:26:16Z

Tonypartridge:

{{Joomla version|version=2.5|time=and after}}
This is an example of how to send an email from a Joomla component. You would typically put this into your component's controller.
=== Fetch the Mail Object ===
A reference to the global mail object (JMail) is fetched through the JFactory object. This is the object creating our mail.

<source lang="php">
$mailer = JFactory::getMailer();
</source>

=== Set a Sender ===
The sender of an email is set with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setSender setSender]. The function takes an array with an email address and a name as an argument. We fetch the site's email address and name from the global configuration. These are set in the administration back-end (Global Configuration -> Server -> Mail Settings).

<source lang="php">
$config = JFactory::getConfig();
$sender = array(
$config->get( 'mailfrom' ),
$config->get( 'fromname' )
);

$mailer->setSender($sender);
</source>

In 3.1, $config->getValue() should be changed to $config->get()

=== Recipient ===
You set the recipient of an email with the function [http://api.joomla.org/1.5/Joomla-Framework/Mail/JMail.html# addRecipient].
To set the email address to the currently logged in user, we fetch it from the user object.

<source lang="php">
$user = JFactory::getUser();
$recipient = $user->email;

$mailer->addRecipient($recipient);
</source>

If we had multiple recipients, we would put each recipient's email address in an array.

<source lang="php">
$recipient = array( 'person1@domain.com', 'person2@domain.com', 'person3@domain.com' );

$mailer->addRecipient($recipient);
</source>

=== Create the Mail ===
We need to set a subject line and create the text body. The subject is set with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setSubject setSubject].

The easy way to create an email body is as a string with plain text. Use the function [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setBody setBody] to add a message to the mail body. You can also attach a file with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#addAttachment addAttachment]. It takes a single file name or an array of file names as the argument.

<source lang="php">
$body = "Your body string\nin double quotes if you want to parse the \nnewlines etc";
$mailer->setSubject('Your subject string');
$mailer->setBody($body);
// Optional file attached
$mailer->addAttachment(JPATH_COMPONENT.'/assets/document.pdf');
</source>

If you prefer to format your email in HTML, you need to tell the mailer it is HTML. This is done with [http://api.joomla.org/Unknown/PHPMailer.html#methodIsHTML IsHTML]. When sending HTML emails you should normally set the [http://api.joomla.org/Unknown/PHPMailer.html#$Encoding Encoding] to base64 in order to avoid unwanted characters in the output. The subject line and any attachments are handled as above, with the exception of images embedded in the HTML. These are taken care of with the function [http://api.joomla.org/Unknown/PHPMailer.html#AddEmbeddedImage AddEmbeddedImage].

<source lang="php">
$body = '<h2>Our mail</h2>'
. '<div>A message to our dear readers'
. '<img src="cid:logo_id" alt="logo"/></div>';
$mailer->isHtml(true);
$mailer->Encoding = 'base64';
$mailer->setBody($body);
// Optionally add embedded image
$mailer->AddEmbeddedImage( JPATH_COMPONENT.'/assets/logo128.jpg', 'logo_id', 'logo.jpg', 'base64', 'image/jpeg' );
</source>

Normally you would leave any images on your server and refer to them with an ordinary HTML image tag, to reduce size of the mail and the time sending it.

=== Sending the Mail ===
The mail is sent with the function [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#Send Send]. It returns '''true''' on success or a JError object.

<source lang="php">
$send = $mailer->Send();
if ( $send !== true ) {
echo 'Error sending email: ' . $send->__toString();
} else {
echo 'Mail sent';
}
</source>

You would probably want to write your own error handler, if there is an error sending the mail.

The JMail object is used for sending mail in Joomla's contact manager. See the file joomla/components/com_contact/controller.php

===See also===
* [http://api.joomla.org/Joomla-Platform/JFactory.html#getMailer JFactory->getMailer on api.joomla.org]

[[Category:Development]]
[[Category:Component Development]]

Client-side form validation

2017-01-03T06:05:43Z

Tonypartridge: Added information about lists

{{JSplit}}
==Introduction==

Joomla 1.5 and later versions contain a behavior, which allows your form and its elements to be validated at client side, i.e., before it is submitted to the server. The behavior enables the script '''validate.js''' and used [http://mootools.net MooTools] up to version 3.2 and jQuery from version 3.3.

Note: Validate.js is a validation system different from the one provided by [http://mootools.net/docs/more/Forms/Form.Validator MooTools].

==Enable the Validation==

Add a behavior to your form view template. For Joomla versions before 1.5.2:
<source lang="php">
JHtmlBehavior::formvalidation();
</source>
For versions from 1.5.2 to 3.3.6:
<source lang="php">
JHtml::_('behavior.formvalidation');
</source>
For versions from 3.4:
<source lang="php">
JHtml::_('behavior.formvalidator');
</source>

Add the form-validate class to your form
<source lang="html4strict">
<form class="form-validate"> ... </form>
</source>

Add a validation class to your form field declarations. Joomla adds a ''blur'' handler to validate the form field when the user moves away from the field.
<source lang="xml">
<field name="email" type="text" class="required validate-email" size="30" />

//For radios make sure the class is applied to the options:

<field name="ThisorThat" type="radio" label="Please say if it was full-time or the part-time equivalent?" >
<option value="This" class="required">This</option>
<option value="That" class="required">That</option>
</field>
</source>

For lists which are required the first option should have a value of "" as per:

<source lang="xml">
<field name="selectme" type="list" required="true" label="Please say if it was full-time or the part-time equivalent?" >
<option value="">Please Select</option>
<option value="This">This</option>
<option value="That">That</option>
</field>
</source>

The following classes are available:
* required
* validate-username
* validate-password
* validate-numeric
* validate-email
* validate-[custom] -> custom defined - see below

Note: Joomla 2.5 translates the ''required'' field attribute into a ''required'' class value.

Finally, add the ''validate'' class to your submit button. This will cause an ''onclick'' handler to be added that validates the whole form. The form will only be submitted if it is valid.
<source lang="html4strict">
<button type="submit" class="validate">Submit form</button>
</source>

==Custom Handlers==

If you want a custom handler, you can add one to the class, as in the following example (to be defined AFTER loading validate.js):

MooTools
<source lang="javascript">
window.addEvent('domready', function(){
document.formvalidator.setHandler('birth', function(value) {
regex=/^\d{4}-\d{2}-\d{2}$/;
return regex.test(value);
});
});
</source>
jQuery
<source lang="javascript">
jQuery(document).ready(function(){
document.formvalidator.setHandler('birth', function(value) {
regex=/^\d{4}-\d{2}-\d{2}$/;
return regex.test(value);
});
});
</source>
You can then assign validate-birth to any field to make it validate as yyyy-mm-dd. (Valid date is not checked!)

If you want a custom handler to check both the passwords (Password and Confirm Password) are same, please add the following script after the validate.js:

MooTools
<source lang="javascript">
window.addEvent('domready', function(){
document.formvalidator.setHandler('passverify', function (value) {
return ($('password').value == value);
});
});
</source>

jQuery
<source lang="javascript">
jQuery(document).ready(function(){
document.formvalidator.setHandler('passverify', function (value) {
return (jQuery('input[type=password]').value == value);
});
});
</source>
Add the class "validate-passverify" to the input field as below:
<source lang="html4strict"><input class="inputbox required validate-passverify" type="password" id="password2" name="password2" size="40" value="" />
</source>

==Styling/Templating Invalid Elements==

Joomla assigns the ''invalid'' class to form fields that do not pass the validation test. ''invalid'' is also added to the field labels.
If you style the class in the cascading style sheet, your users will be able to see which fields are wrong. For instance:
<source lang="css">
.invalid {
border-color: red !important;
}
</source>
Some site templates may already contain such definition. (This one is taken from ''beez_20''.)



==Problem & workaround with JToolBar==
If you are using JHTML::_('behavior.formvalidation') with JToolBar, for example use in backend, the above method will not work. This is because it depends on onSubmit event which did not fire when we call form.submit via JavaScript. To work around this, we have to move the code in onSubmit to be in submitbutton function override. This will look like this:-
<source lang="javascript">
<script type="text/javascript">
/* Override joomla.javascript, as form-validation not work with ToolBar */
function submitbutton(pressbutton) {
if (pressbutton == 'cancel') {
submitform(pressbutton);
}else{
var f = document.adminForm;
if (document.formvalidator.isValid(f)) {
f.check.value='<?php echo JUtility::getToken(); ?>'; //send token
submitform(pressbutton);
}
else {
var msg = new Array();
msg.push('Invalid input, please verify again!');
if ($('title').hasClass('invalid')) {
msg.push('<?php echo JText::_('COM_JONGMAN_ERROR_SCHEDULE_TITLE_IS_REQUIRED')?>');
}
if($('admin_email').hasClass('invalid')){
msg.push('<?php echo JText::_('COM_JONGMAN_ERROR_INVALID_EMAIL')?>');
}
alert (msg.join('\n'));
}
}
}
</script>
</source>

==More on mootools validation==
More available classes on the mootools site here: [http://mootools.net/docs/more/Forms/Form.Validator#Validators http://mootools.net/docs/more/Forms/Form.Validator#Validators]

==Server- or Client-side validation?==
[[Form validation]]

<noinclude>[[Category:Tutorials]][[Category:Development]][[Category:Component Development]]</noinclude>

List form field type

2017-01-03T06:00:38Z

Tonypartridge:

<noinclude><languages /></noinclude>
<translate>
The '''list''' form field type provides a drop down list or a list box of custom-defined entries. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.</translate>
[[Image:Params.list.jpg|right]]
<translate>
* '''type''' (mandatory) must be ''list''.</translate>
<translate>
* '''name''' (mandatory) is the unique name of the field.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''default''' (optional) is the default list item value.</translate>
<translate>
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.</translate>
<translate>
* '''class''' (optional) is a CSS class name for the HTML form field. If omitted this will default to 'inputbox'.</translate>
<translate>
* '''multiple''' (optional) is whether multiple items can be selected at the same time (''true'' or ''false'').</translate>
<translate>
* '''required''' (optional) if set to true, the first field option should be empty, see last example.</translate>

<translate>
The XML <code><field></code> element must include one or more <code><option></code> elements which define the list items. The text between the <code><option></code> and <code></option></code> tags is what will be shown in the drop down list and is a translatable string. The <code><option></code> tag takes the following argument:</translate>

<translate>
* '''value''' (mandatory) is the value that will be saved for the field if this item is selected.</translate>

<translate>
Tip: Don't forget to close the field definition with <code></field></code>.</translate><br />
<translate>
Tip: Add first an option without a value, with a text like "Select an option". Otherwise, in case of a required field, the first option with a value gets silently selected (i.e., without the user choosing it). This text will typically be seen by users before clicking the dropdown list.</translate>

<translate>
Example XML field definition:</translate>
<source lang="xml"><field name="mylistvalue" type="list" default="" label="Select an option" description="">
<option value="0">Option 1</option>
<option value="1">Option 2</option>
</field>
</source>

<translate>
Example XML field definition with required field value:</translate>
<source lang="xml"><field name="mylistvalue" type="list" default="" required="true" label="Select an option" description="">
<option value="">Please Select</option>
<option value="0">Option 1</option>
<option value="1">Option 2</option>
</field>
</source>

<translate>=== See also === </translate>
<translate>

* [[S:MyLanguage/Filelist form field type|Filelist form field type]]
* [[S:MyLanguage/Folderlist form field type|Folderlist form field type]]
* [[S:MyLanguage/Imagelist form field type|Imagelist form field type]]
* [[S:MyLanguage/Standard form field types|List of standard form field types]]
</translate>

<noinclude>
<translate>

[[Category:Standard form field types]]
</translate>
</noinclude>

List form field type

2017-01-03T05:57:40Z

Tonypartridge: Shows JForm XML which is required.

<noinclude><languages /></noinclude>
<translate>
The '''list''' form field type provides a drop down list or a list box of custom-defined entries. If the field has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.</translate>
[[Image:Params.list.jpg|right]]
<translate>
* '''type''' (mandatory) must be ''list''.</translate>
<translate>
* '''name''' (mandatory) is the unique name of the field.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''default''' (optional) is the default list item value.</translate>
<translate>
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.</translate>
<translate>
* '''class''' (optional) is a CSS class name for the HTML form field. If omitted this will default to 'inputbox'.</translate>
<translate>
* '''multiple''' (optional) is whether multiple items can be selected at the same time (''true'' or ''false'').</translate>

<translate>
The XML <code><field></code> element must include one or more <code><option></code> elements which define the list items. The text between the <code><option></code> and <code></option></code> tags is what will be shown in the drop down list and is a translatable string. The <code><option></code> tag takes the following argument:</translate>

<translate>
* '''value''' (mandatory) is the value that will be saved for the field if this item is selected.</translate>

<translate>
Tip: Don't forget to close the field definition with <code></field></code>.</translate><br />
<translate>
Tip: Add first an option without a value, with a text like "Select an option". Otherwise, in case of a required field, the first option with a value gets silently selected (i.e., without the user choosing it). This text will typically be seen by users before clicking the dropdown list.</translate>

<translate>
Example XML field definition:</translate>
<source lang="xml"><field name="mylistvalue" type="list" default="" label="Select an option" description="">
<option value="0">Option 1</option>
<option value="1">Option 2</option>
</field>
</source>

<translate>
Example XML field definition with required field value:</translate>
<source lang="xml"><field name="mylistvalue" type="list" default="" required="true" label="Select an option" description="">
<option value="">Please Select</option>
<option value="0">Option 1</option>
<option value="1">Option 2</option>
</field>
</source>

<translate>=== See also === </translate>
<translate>

* [[S:MyLanguage/Filelist form field type|Filelist form field type]]
* [[S:MyLanguage/Folderlist form field type|Folderlist form field type]]
* [[S:MyLanguage/Imagelist form field type|Imagelist form field type]]
* [[S:MyLanguage/Standard form field types|List of standard form field types]]
</translate>

<noinclude>
<translate>

[[Category:Standard form field types]]
</translate>
</noinclude>