Jeroens blog

Today I released Validator version 0.2, on which I’ve been working the last 2 days. It features massive rewriting to make it more flexible, and has some added functionality. Let’s have a look at what changed.

The most important change is, without any doubt, the new list support. Validator 0.1 had a list type, which allowed you to have enumerations of values and do crude validation on them. This version now supports lists of a type, instead of seeing list as a type. So you can now create lists of strings, lists of integers, and even lists of custom types you add. This new approach also allows per-item-validation and per-item-defaulting. This means you can set an in_array criteria, which will then be enforced for every value in your list. Closely related to this new form of list support are the new list criteria, which allow you to validate lists as a whole. At the moment the only 2 build in list criteria are item_count and unique_items, but like for regular criteria, you can hook into Validator and add your own.

Another important change are the output formats. Output formats allow you to specify additional formatting that needs to be done with the parameter value, before it is retrieved from Validator. There are currently 6 build in types, which are array, list, boolean, boolstr, string and unique_items, but again you can hook into this list via Validator. The awesome thing about output formats is that it greatly reduces the mess you otherwise have with converting your parameters from user input to true data structures. You can even specify multiple output formats, which will then do their formatting one by one.

Other things brought by Validator 0.2 include some new criteria (is_boolean, has_length and regex), a new error level, Validator_ERRORS_MINIMAL, new parameter types (boolean, number and char) and support for Validator_ERRORS_WARN in ValidatorManager.

Equally important as the changes made is that the documentation has been completely updated, to give in-depth cover of how Validator works, and how you should use it.

Both Maps and Semantic Maps 0.5.1 use Validator 0.2, allowing them to throw away a lot of repetitive, dumb manipulation, code that has been their since the initial versions of those extensions

Downloads:

• Validator 0.2 (zip)
• Validator 0.2 (7z)
• Validator 0.2 SVN tag

It has been over a week since I posted about any MediaWiki stuff, which can very well be a record since I started my blog. The reason for this is cause I’ve been busy with a lot of projects. You’ll hear about them all later on, but now I just want to provide an overview of the work I’ve been doing on my new MediaWiki extension: Validator.

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.

The main functionality is:

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

Validator has not yet been released, but will be soon. Although not all documentation is ready yet, most of the information needed to use it can already be found in the implementation section of the documentation. Both the development versions of Maps and Semantic Maps are currently using Validator for their parameter handling. The next release of those extensions, 0.5, will therefore feature strict parameter validation, and be dependent on Validator.

Oh, and I got the 60000th MediaWiki commit with the changes I made to Maps to work with the last alpha of Validator – wooot!

One of the big new features in Maps 0.5 will be strict parameter validation. This means Maps will allow you to get specific errors or warnings when entering invalid values or parameters.

The setting determining the strictness of the validation, which can be changes in your LocalSettings file, currently accepts 4 values:

• Maps_ERRORS_NONE : Maps will not show any errors, and make the best of the imput it got.
• Maps_ERRORS_WARN : Maps will make the best of the imput it got, but will show warnings for omitted coordinates.
• Maps_ERRORS_SHOW : Maps will make the best of the imput it got, but will show a list of all errors.
• Maps_ERRORS_STRICT: Maps will only show a map when there are no errors, if there are, a list of them will be shown.

The underneath example demonstrates an error list that can be generated when the validation level is on Maps_ERRORS_SHOW or Maps_ERRORS_STRICT. In case of the former, it’ll be shown below the map,while in case of the later, it’ll be shown instead of any map. The error messages are of course fully internationalized.

The validation is done via a new class dedicated to parameter validation. To be able to validate anything, you need to feed it two things: an associative array containing the raw parameter names and their values, and a somewhat more complex, nested, array containing the allowed parameter and their meta data, such as aliases and default values. The class also provides a hook for validation types, allowing you to do specific or complex validation that is not build in. The handling of the different strictness levels and generation of the actual error messages is done by another class that uses the first to validate and get the errors. Both classes do not contain any Maps specific code, so can be used to validate the parameter of any parser function. I’m planning to split this code, after it has reached a beta level, into a separate extension, that will probably be named “Validator”. This extension will be bundled with Maps, and will not any additional steps to the installation process.

Together with implementing this new feature, I did a big overhaul of the parameter handling in Maps and Semantic Maps. Instead of the two level system, containing general parameters, and service specific parameters, that was used in Maps, there now is a four level system. The first level are the general parameters, shared by everything. These include things like width, height and zoom. Feature specific parameters make up the second level, while the third one holds service specific parameters. The last level are the parameters specific to a combination of service and feature. Maps goes through these levels, starting with the upper one, and overriding it with the following. This allows more specific behaviour and is required to be able to validate the parameters in some instances.

The changes I made to Maps and Semantic Maps during these rewrites are responsible for what are probably my biggest commits to both extensions yet.

• Changes to Maps (rev 59531)
• Changes to Semantic Maps (rev 59532)

Due to the extend of changes I made, and the lack of thorough tests yet, I expect multiple issues with this code, including several severe ones, so I advice against using the latest SVN code for the moment, except for testing purposes of course. I hope to have the code refined and bug hunted in the coming week, so I can put it in a new extension and release it. During this period I’ll also start working on the other new features planned for 0.5, so you can expect more news on this soon.