Kauri Documentation
10.3 Building Custom ControlsBook Index10.3.2 Custom Validators

10.3.1 Custom Formatters


The formatters in the kauri forms framework are simple and straightforward components that handle conversion between typed values and their string-representations.

The 'field' section of the Form Concepts page explains where those conversions fit in.

Formatters are expected to cover the conversion in both directions. Therefore two methods should be implemented:

  1. format:
  2. parse:

During either conversion one can decide that the offered input argument isn't suitable (This will most likely occur during 'parse' from string to typed value only.)  In such cases the implementation should just 'throw' a String-message, which will be displayed to the end user in the same way as a validation error.


The framework offers a base class to start your own formatter from.  Its main advantage is a re-usable 'fail' method that will ensure the required raising of validation error in the correct manner (and some recurring features like i18n, parameter injection etc etc)

( function( $) {

    var kf = $.org.kauriproject.forms;
    var formatters = kf.formatters;

The anonymous function construct above is a know technique to ensure no top level naming conflicts will occur. The variables we declare form a shorthand for the namespaces relevant for Kauri.

    $.inherit(MyFormatter, kf.Formatter);
    function MyFormatter( ) {

With the $.inherit we declare our control to be a subclass of the base control class. 

The needed parse/format methods can then just be implemented as needed:

    MyFormatter.prototype.parse() = function(valstr) {

        // Expected behaviour is to trim input and intrerpret empty strings as containing "No Value"
        valstr = $.trim(valstr);
        if (valstr == "")
            return undefined;

        var value = ..... // code doing the parsing

        //in case of error:
        this.fail("this input: {0} is does not meet this pattern: {1}", [valstr, pattern]); // messages starting with 'i18n:' will be translated

        // or 
        this.fail("i18n:message-key", [args-to-inject]); // messages starting with 'i18n:' will be translated

        // or if all just works smoothly:
        return value; // should be a typed value

    MyFormatter.prototype.format = function(value) {

        // Expected behaviour is to communicate 'no-value' as an empty string to the end-user
        // Actually: in case of wire-value formatting this rule does not apply, 
        //    however this will be checked in the system and undefined will be returned automatically.
        //    Like this you can re-use formatters for both purposes: 'wire' and 'user'
        if (val == undefined)
            return "";
        return val.toString();

Note: the above is the default implementation for format: so if your typed value implementation has a fitting toString() then you don't need to code any additional format() method.

    kf.formatters.put("my-format", MyFormatter);

Finally the above line will register your new control which makes it available for referencing it from the fconf.


Alternatively the formatter can be specified inside the form-config by placing it in the 'formatters' section. In that case the behaviour of the described base class will be automatically applied to it, allowing you to leav out quite some boiler-plate code:

Assuming the dafult format() is ok, you could deal with it like this:

var fconf = {

    'formatters':    {
        'my-formatter' : {
            'parse': function(valstr) {
                   // implementation here, including available calls to this.fail();
10.3 Building Custom Controls10.3.2 Custom Validators