Extension:ParamProcessor

From MediaWiki.org
(Redirected from Extension:Validator)
Jump to: navigation, search
MediaWiki extensions manual - list
Crystal Clear action run.png
ParamProcessor

Release status: stable
Green check.svg
Implementation Tag, Parser function, Hook
Description Provides generic parameter handling support to other extensions
Author(s) Jeroen De Dauwtalk
Last version 0.5.1 (2012-11-21)
MediaWiki 1.17+
PHP 5.2.3 or later
Database changes no
License GPL v3 or later
Download
Download snapshot (Git master)
Git [?]:
Hooks used
ParserFirstCallInit

UnitTestsList
Check usage and version matrix
Bugs: list open list all report

The ParamProcessor extension, formerly known as Validator, is a parameter processing framework that provides a way to declaratively define a set of parameters and how they should be processed. It can take such declarations together with a list of raw parameters and provide the processed values.

Contents

Functionality overview [edit]

A brief description of the core functionality.

This section needs updating for versions 0.5 and 1.0. It currently reflects version 0.4.x.

Parameter validation [edit]

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 [edit]

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 foobar=yes, no, no, yes, no. 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 [edit]

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.

Automatic documentation generation [edit]

Since version 0.4.3, Validator has a "describe" parser hook which automatically generates documentation for one or more parser hooks. This documentation includes a description of the parser hook, a table with its parameters and syntax examples. The result can be either directly viewed in a wiki page, or displayed as wikitext, so it can be copied over to another page. (example)

Setup [edit]

Download [edit]

Quick link: Download Validator 0.5.1 (.tar.gz file)

You can download the extension directly from the MediaWiki source code repository (browse code). You can get:

One of the extensions tags

Not all extensions have tags. Some extensions have tags for each release, in which case those tags have the same stability as the release. To download a tag

  • Go to the tags list
  • Click the name of the tag you want to download
  • Click "snapshot"
The latest version of one of the extensions branches

Each extension has a master branch containing the latest code (might be unstable). Extensions can have further branches as well.

  • Go to the branches list
  • Click the branch name
  • Click "snapshot"
A snapshot made during the release of a MediaWiki version.

This might be unstable and is not guaranteed to work with the associated MediaWiki version.

After you've got the code, save it into the extensions/ParamProcessor directory of your wiki.

If you are familiar with git and have shell access to your server, you can obtain the extension, with all its tags and branches, as follows:

cd extensions
git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/ParamProcessor.git

Installation [edit]

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:

# Validator
require_once( "$IP/extensions/Validator/Validator.php" );

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

Change log [edit]

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

Validator-codefrequency.svg

Usage [edit]

listerrors [edit]

Description: Lists errors (and warnings) that occured in parser hooks added via Validator. Only lists for parser hooks added above where listerrors is inserted; place listerrors at or near the bottom of the page to get all errors.

Implemented as both parser function and as tag extension.

Parameters [edit]

# Parameter Aliases Type Default Description
1 minseverity - Text minor The minimum severity of an issue for it to be listed.

Syntax [edit]

Tag extension with only the required parameters.

<listerrors />

Tag extension with all parameters.

<listerrors minseverity="{Text}" />

Tag extension with all parameters using the default parameter notation.

<listerrors>{minseverity, Text}</listerrors>

Parser function with only the required parameters.

{{#listerrors:}}

Parser function with all parameters.

{{#listerrors:minseverity={Text}}}

Parser function with all parameters using the default parameter notation.

{{#listerrors:{minseverity, Text}}}

describe [edit]

Description: Generates documentation for one or more parser hooks defined via Validator.

Implemented as both parser function and as tag extension.

Parameters [edit]

# Parameter Aliases Type Default Description
1 hooks - List of text items listerrors, describe, coordinates, display_map, display_point, distance, finddestination, geocode, geodistance, subpages The parser hooks for which to display documentation.
- pre - Yes/no off Allows you to get the actual wikitext for the documentation, without it being rendered on the page.

Syntax [edit]

Tag extension with only the required parameters.

<describe />

Tag extension with all parameters.

<describe hooks="{List of text items}" pre="{Yes/no}" />

Tag extension with all parameters using the default parameter notation.

<describe pre="{Yes/no}">{hooks, List of text items}</describe>

Parser function with only the required parameters.

{{#describe:}}

Parser function with all parameters.

{{#describe:hooks={List of text items}|pre={Yes/no}}}

Parser function with all parameters using the default parameter notation.

{{#describe:{hooks, List of text items}|pre=Yes/no}}

Supported languages [edit]

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.


Contributing to the project [edit]

Bugs and patches [edit]

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

git diff >descriptivename.patch

Then upload it somewhere and link to it from the talk page. Bug reports should also be added here. You can also send them to Jeroen De Dauw, jeroendedauw -at- gmail.com.

Feature requests [edit]

Feel free to add feature requests to the discussion page.

Translating [edit]

Translation of Validator 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 [edit]

External links [edit]

Sites that use Validator [edit]

Retrieved from "http://www.mediawiki.org/w/index.php?title=Extension:ParamProcessor&oldid=684116"