Extension:Validator

Description
Validator is an extension that makes parameter validation functionality available to other extensions. This enables other extensions to validate parameters, set them to their defaults, and generate error messages, while only defining the parameters and their criteria. The goal of this extension is to facilitate the handling of parameters in other extension, and generalize the error output. By itself, it does not add any functionality to the user end.

Functionality overview

 * Parameter validation: Parameters that are provided in an array where the keys represent their name, and the values their value, can easily be validated against a set of criteria. During this validation, errors and their types will be stored, and invalid parameters will be separated from valid ones. The only thing an other extension needs to do is define the criteria to validate against. A set of criteria types (which include check to see if something is a number, is within a range, or in an array) is provided by Validator, and can be used without any extra coding. When a criteria type that is not supported is required, you can hook into the Validator criteria types and add your own validation functions.


 * Default value handling: Parameters that are invalid, or simply not provided, can be set to their default values. These default values need to be specified by the extension the parameters belong to.


 * Error handling: Since the errors and their types are stored during validation, you can create error messages by retrieving this data and parsing it. Validator also provides a manager class that can provide you with a list of internationalized and specific errors. Via a validation level setting Validator provides, you can determine how the errors should be reflected on your wiki page. This can go from completely ignoring any errors to showing a complete list of all errors underneath the regular output, or even hiding the regular output and only showing the errors.

Installation
Once you have downloaded the code, place the 'Validator' directory within your MediaWiki 'extensions' directory. Then add the following code to your LocalSettings.php file:

Note that you need to place this code before the inclusion of any extensions depending on Validator.

Version
Validator is currently not yet released.

Planned features
The underneath list contains a list of planned features:

Version 0.2

 * Add hook for parameter types.
 * Add per-item-validation and per-item-defaulting for lists.

Change log
This list only contains the versions and their release dates. For a list of all changes made, view the change log.

Supported languages
Validator has support for English, Belarusian, Breton, Lower Sorbian, Spanish, French, Galician, Swiss German, Upper Sorbian, Hungarian, Interlingua, Indonesian, Japanese, Ripoarisch, Macedonian, Dutch, Piedmontese, Portuguese, Russian, Swedish, Vietnamese and others.

Parameter definition
(I'm still working on this, changes can be expected before the first release.)

Integer example:

$yourParameters['parameterName'] = array (	'aliases' => array('parameter-name', 'paramName'),	'required' => true,	'type' => 'integer',	'criteria' => array( 'in_range' => array(0, 99), 'is_prime' => array ),	'default' => '42' );

List example:

$yourParameters['parameterName'] = array (	'type' => 'list',	'delimiter' => ',',	'criteria' => array( 'all_in_array' => array('possible value', 'another one'), ), );

Keys:


 * aliases: Optional. Array. When omitted, empty array will be assumed.
 * required: Optional. Boolean. When omitted, false will be assumed.
 * type: Optional. String. Values like string, integer, list, ect. When omitted, string will be assumed. The type will be used to create adittional criteria. New types can be added via Validator class hook.
 * criteria: Optional. Associative Array. When omitted, empty array will be assumed. Each array element has the criteria name as it's key, and criteria specifications in an array as value. New criteria definitions can be added via Validator class hook.
 * default: Optional. Mixed. When omitted, empty string will be assumed.

Validator class
This class provides the methods required to validate your parameters, track the errors and set any default values. In most cases you'll want to do parameter validation via class ValidatorManager, which will create an instance of a Validator. You are entirely free to directly call the Validator class to do any custom interaction, like error message generation.

For an example of how to interact with this class, see the source of ValidatorManager.

ValidatorManager class
The ValidatorManager class contains wrapper functions for the most common interaction with the Validator class. It contains 2 methods:


 * manageMapparameters: Validates the provided parameters, and corrects them depending on the error level. Returns the valid parameters or false when the output should not be shown. The later is determined by the current $egValidatorErrorLevel.
 * getErrorList: Returns a string containing an HTML error list, or an empty string when there are no errors.

This is a simplified version of how the Maps extension uses the ValidatorManager class:

Bugs and patches
If you found some bug and fixed it, please create a patch by going to the "Validator" directory, and typing:

svn diff >descriptivename.patch

Then add the patch to the bugs page. Bug reports should also be added here. You can also send them to Jeroen De Dauw, jeroendedauw -at- gmail.com.

Feature requests
Feel free to add feature requests to the discussion page.

Translating
Translation of Maps is done through translatewiki.net. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on translatewiki.net, then request permission from the administrators to translate a certain language or languages on this page (this is a very simple process). Once you have permission for a given language, you can log in and add or edit whatever messages you want to in that language.

Translations for this documentation, especially the extension description, are also welcome.

Extensions that use Validator

 * Maps (Since 0.5)
 * Semantic Maps (Since 0.5)