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.

Download

 * Validator0.1.zip 56.61 KB
 * Validator0.1.7z 36.08 KB

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/REL_0_1. From a command line, you can call the following:

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

Package downloads
Validator comes bundled with every release of Maps and Semantic Maps.

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.3

 * Add hook for parameter types.


 * Add hook for validation types error messages.

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


 * Version 0.1 (20010-12-17)

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

Parameter definition
This section contains detailed explanations of how each parameter definition element works. These examples can give you an idea of what a realist parameter definition looks like:

Aliases
Key:

Required
Key:

Default value
Key:

Type
Key:

The underneath table contains all build in parameter types. If you want do add your own type with custom behaviour, look at how to hook a parameter type.

Table columns:
 * Example: An example of a value of this type.
 * Version: The version in which the last change to this type's behaviour was made.

Lists
Key: part of

Since version 0.2, you can specify lists of a certain type. For example, you can have a list of integers, or a list of strings.

You can specify a parameter is a list of a type, instead of just a single value of a type, by changing your type definition into an array, and adding the list identifier as second element. The underneath examples demonstrate how to change the definition of an integer type, into a list of integers.

Integer type definition 'type' =>'integer'

Integer list type definition 'type' => array('integer', 'list')

You can also specify the delimiter for the list, by adding it as third element to your type definition array. When omitted, comma will be assumed.

Integer list type definition with custom delimiter 'type' => array('integer', 'list', ';')

Criteria
Key:

The underneath table contains all build in parameter criteria types. If you want do add your own type with custom criteria, look at how to hook a criteria type.

These criteria look at single values. If the type of the parameter is a list, every list item of the value will be checked against these criteria. If you want to validate a list as a whole however, you need to use list criteria.

List criteria
Key:

List criteria are criteria that look at a list as a whole, not the individual values. Like regular criteria, you can add your own custom ones, see how to hook a criteria type.

Output type
Key:

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:

Error level
The error level is a setting defined by Validator that indicates in which situations errors should be shown, and how extensive they should be. Validator uses this setting internally in the ValidationManager class to generate error messages. Extensions using Validator can also use this setting in their own code, if not all error handling goes via Validator. An example of such an implementation can be found in the Maps extension, where maps will not be shown when there are no valid coordinates. Maps will only show a warning when the error level is equal to or above Validator_ERRORS_MINIMAL.

The error level can be set by changing the value of $egValidatorErrorLevel in LocalSettings.php, after the inclusion of Validator. The default is Validator_ERRORS_SHOW.

The possible error level values are discussed below. Note that the described behaviours are implemented in Validator, but not necessary in all extensions using Validator. The later is the task of the authors of the extensions using Validator.

None
Value:

No errors will be shown under any circumstances, including these where no output can be shown for the input of which the parameters got validated.

Minimal
Value:

The only instance where an error can be shown is when no output can be shown for the input of which the parameters got validated. In all other circumstances, any present errors will be treated as best as they can, by means of defaulting.

Warn
Value:

A warning will be shown when there are errors present. Any present errors will be treated as best as they can, by means of defaulting.

Show
Value:

All present errors will be reported in the form of a list. Any present errors will be treated as best as they can, by means of defaulting.

Strict
Value:

All present errors will be reported in the form of a list. If there is at least one error, even if it can be solved by means of defaulting, the regular output will not be generated and shown. To see the regular output, the user will first have to fix the reported errors.

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)