Extension:Validator

For documentation on validator 0.3.x, see this page.

Validator is a parameter handling framework which aims to facilitate common parameter handling tasks, such as parsing, validation, and error handling, for other MediaWiki extensions.

Functionality overview
A brief description of the core functionality.

Parameter validation
You can validate a list of raw parameters against a set of parameter definitions using the Validator class. Validator will then determine which criteria are not met, which parameters are missing and which ones are unknown. Incorrect or missing values are replaced by the default value for their parameter, and all errors are stored.

The raw parameters can be either key value pairs, such as provided by tag extensions, or 'foo=bar' elements, such as provided by parser functions. In case of the later, Validator takes care of the parsing and provides out-of-the-box support for default parameters. Validator also provides a ParserHook class which enables you to create parser hooks (tag extensions and parser functions) that seamlessly integrate with the other functionality provided by Validator.

Parameter manipulation
Validator not only Validates your parameters, but also further handles them so that you get them into a convenient format and don't need to do any further manipulations. A simple example is a parameter which expects a list of "yes" and "no", such as. What validator will return is an array containing booleans. This removes the need for defining the same handling all over your code, and allows you to get right to what you actually want to write. Validator provides a set of common manipulations, which is easily extendible by other extensions to add more specific handling.

Errors and warnings
Validator provides several classes to describe and keep track of parameter validation related errors. Such errors can be shown inline or at the end of the page using the listerrors parser hook. All errors have a severity, and you can configure which actions need to be taken for errors with a certain severity. For example if they should be shown inline or not. This functionality works out-of-the-box when using the ParserHook class and the criteria classes provided by Validator in your parameter definitions, but can easily be used and extended by in other situations.

Download
You can find the current downloads on the Validator google code project. For a list of all downloads, including deprecated ones, see here.

Subversion downloads
You can also download the code directly via SVN from the MediaWiki source code repository, at http://svn.wikimedia.org/svnroot/mediawiki/tags/extensions/Validator/. From a command line, you can call the following (where X_X_X is the version number):

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/tags/extensions/Validator/REL_X_X_X Validator

To get the latest version of Validator, just check out from svn trunk, at http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/Validator.

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/Validator Validator

Package downloads
Validator comes bundled with every release of Maps and Semantic Maps. You can get their distributions here.

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 at version 0.4.1.

Planned for 0.4.2

 * Throw out the toLowerCase property in the Parameter class. It makes no sense to have it as a special thing, as it can perfectly be done using the regular approach, and is currently causing issues all over the place.

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


 * Version 0.4 (2010-10-15)
 * Version 0.4.1 (2010-10-20)
 * Version 0.4.2 (2010-10-28)


 * Version 0.3 (2010-05-31)
 * Version 0.3.1 (2010-06-04)
 * Version 0.3.2 (2010-06-07)
 * Version 0.3.3 (2010-06-20)
 * Version 0.3.4 (2010-07-08)
 * Version 0.3.5 (2010-07-26)
 * Version 0.3.6 (2010-08-26)


 * Version 0.2 (2009-12-25)
 * Version 0.2.1 (2010-02-01)
 * Version 0.2.2 (2010-03-01)


 * Version 0.1 (2009-12-17)

Supported languages
Validator has support for over 45 languages, including English, Afrikaans, Gheg Albanian, Arabic, Belarusian, Bulgarian, Breton, Bosnian, Czech, German, Lower Sorbian, Greek, Esperanto, Spanish, Finnish, French, Franco-Provençal, Galician, Swiss German, Hebrew, Upper Sorbian, Hungarian, Interlingua, Indonesian, Italian, Japanese, Colognian, Luxembourgish, Macedonian, Dutch, Norwegian, Occitan, Polish, Piedmontese, Portuguese, Brazilian Portuguese, Romanian, Russian, Sinhala, Swedish, Telugu, Tagalog, Turkish, Ukrainian, Vietnamese, Simplified Chinese and others.

Implementation
This section describes how you can use Validator in your own extension. Some good examples can be found in the parserhook directory of the Maps extension. Poke Jeroen De Dauw if anything here isn't clear to you.

Parser hooks
TODO

Parameters
TODO

List parameters
TODO

Criteria
TODO

Manipulations
TODO

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)