Yii 1.1: yii-input-mask

Based on Robin Herbots jquery.inputmask 3.1.34 ,This extension helps the user with the input by ensuring a predefined format.
4 followers

An inputmask helps the user with the input by ensuring a predefined format. This can be useful for dates, numerics, phone numbers.

Highlights:

  • easy to use
  • optional parts anywere in the mask
  • possibility to define aliases which hide complexity
  • date / datetime masks
  • numeric masks
  • lots of callbacks
  • non-greedy masks
  • many features can be enabled/disabled/configured by options
  • supports readonly/disabled/dir="rtl" attributes
  • support data-inputmask attribute
  • multi-mask support

Requirements

...requirements of using this extension (e.g. Yii 1.1 or above)...

Usage

Extract the downloaded zip file and place it inside application extensions directory.

Version 1.1 Changes

  • added the default settings overriding option
  • fixed javascript code replacing bug.
$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "mobile",
                "mask" => '(999) 999-9999',
                "clientOptions" => array("autoUnmask"=> true), /* autoUnmask defaults to false*/
                "defaults"=>array("removeMaskOnSubmit"=>false),
/* once defaults are set will be applied to all the masked fields  removeMaskOnSubmit defaults to true */
            ));

Default masking definitions

  • '9' : numeric
  • 'a' : alphabetical
  • '*' : alphanumeric

There are more definitions defined within the extensions. You can find info within the js-files or by further exploring the options. see

Static masks

These are the very basic of masking. The mask is defined and will not change during the input.

$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "mobile",
                "mask" => '(999) 999-9999'                
            ));

Optional masks

It is possible to define some parts in the mask as optional.

$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "mobile",
                "mask" => "(99) 9999[9]-9999"                  
            ));

Optional masks with greedy false

When defining an optional mask together with the greedy: false option, the inputmask will show the smallest possible mask as input first.

$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "mobile",
                "mask" => "99999[-9999]",
                "clientOptions"=>array("greedy"=>false)   
            ));
 
$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "mobile",
                "mask" => "+44 1865 [x99999]",
                "clientOptions"=>array("greedy"=>false)   
            ));

Dynamic masks

Dynamic masks can change during the input.To define a dynamic part use { }. {n} => n repeats. {n,m} => from n to m repeats. Also {+} and {*} is allowed. + start from 1 and * start from 0.

$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "mobile",
                "mask" => "aa-9{4}",
            ));
 
$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "mobile",
                "mask" => "aa-9{1,4}",
            ));

Alternator masks

The alternator syntax is like an OR statement. The mask can be one of the 2 choices specified in the alternator.

To define an alternator use the |. ex: "a|9" => a or 9 "(aaa)|(999)" => aaa or 999

Also make sure to read about the keepStatic option.

$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "mobile",
                "mask" => '["99.9", "X"]', /must use quotation when defining an array plugin requires this way /
                "definitions"=>array(
                    "X"=>array(
                        "validator"=>"[xX]",
                        "cardinality"=>1,
                        "casing"=>"upper"
                    )
            ));

Define custom definitions

You can define your own definitions to use in your mask. Start by choosing a masksymbol.

validator(chrs, maskset, pos, strict, opts)

Next define your validator. The validator can be a regular expression or a function. The return value of a validator can be true, false or a command object.

Options of the command object

pos : position to insert, c : character to insert, caret : position of the caret, remove : position to remove, refreshFromBuffer : true => refresh validPositions from the complete buffer { start: , end: } => refresh from start to end,

cardinality

Cardinality specifies how many characters are represented and validated for the definition.

prevalidator(chrs, maskset, pos, strict, opts)

The prevalidator option is used to validate the characters before the definition cardinality is reached. (see 'j' example).

definitionSymbol

When you insert or delete characters, they are only shifted when the definition type is the same. This behavior can be overridden by giving a definitionSymbol. (see example x, y, z, which can be used for ip-address masking, the validation is different, but it is allowed to shift the characters between the definitions)

$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "test",
                "mask" => 'y',
                "definitions" => [
                    'f'=>[
                        "validator"=>"[0-9\(\)\.\+/ ]",
                        "cardinality"=>"1",
                        "prevalidator"=>null,
                    ],
                    'g'=>[
                        "validator"=>"function (chrs, buffer, pos, strict, opts) {}",
                        "cardinality"=>1,
                        "prevalidator"=> null,
                    ],
                    'j'=>[
                        'validator'=>'[0-9\(\)\.\+/ ]',
                        'cardinality'=>4,
                        'prevalidator'=>[
                            ['validator'=>'[12]','cardinality'=>1],
                            ['validator'=>'(19|20)','cardinality'=>2],
                            ['validator'=>'(19|20)\\d','cardinality'=>3],                            
                        ],
                    ],
                    'x'=>[
                        "validator"=>"[0-2]",
                        "cardinality"=>1,
                        "definitionSymbol"=>'i'
                    ],
/*Validater as a function doesn't work please avoid doing so */
                    'y' => [
                        'validator' => 'function (chrs, buffer, pos, strict, opts) {
                                        var valExp2 = new RegExp("2[0-5]|[01][0-9]");
                                        return valExp2.test(buffer[pos - 1] + chrs);
                                    }',
                        'cardinality' => 1,
                        'definitionSymbol' => 'i'
                    ],
/*Validater as a function doesn't work please avoid doing so */
                    'z'=>[
                        "validator"=>'function (chrs, buffer, pos, strict, opts) {
                            var valExp3 = new RegExp("25[0-5]|2[0-4][0-9]|[01][0-9][0-9]");
                            return valExp3.test(buffer[pos - 2] + buffer[pos - 1] + chrs);
                        }',
                        "cardinality"=>1,
                        "definitionSymbol"=>'i'
                    ]
                    ]
            ));

aliases

With an alias you can define a complex mask definition and call it by using an alias name. So this is mainly to simplify the use of your masks. Some aliases found in the extensions are: email, currency, decimal, integer, date, datetime, dd/mm/yyyy, etc.

First you have to create an alias definition. The alias definition can contain options for the mask, custom definitions, the mask to use etc.

When you pass in an alias, the alias is first resolved and then the other options are applied. So you can call an alias and pass another mask to be applied over the alias. This also means that you can write aliases which "inherit" from another alias.

/*date 
available date/ time aliases 
dd/mm/yyyy, mm/dd/yyyy, yyyy/mm/dd, dd.mm.yyyy, dd-mm-yyyy, mm.dd.yyyy, mm-dd-yyyy, yyyy.mm.dd, yyyy-mm-dd, datetime, hh:mm t, h:s t, hh:mm:ss, hh:mm,  mm/yyyy
*/
$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "date",
                "clientOptions" => array("alias" =>  "date")
            ));
/*date */
$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "date",
                "clientOptions" => array("alias" =>  "yyyy-mm-dd")
            ));
/* decimal */
$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "cost",
                "clientOptions" => array(
                    "alias" =>  "decimal",
                    "groupSeparator"=>',',
                    "autoGroup"=>true
                    )
            ));
/* ip address */
$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "ip_address",
                "clientOptions" => array("alias" =>  "ip"),
            ));
/* url */
$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "web",
                "clientOptions" => array("alias" =>  "url"),
            ));
/* email */
$this->widget("ext.maskedInput.MaskedInput", array(
                "model" => $model,
                "attribute" => "email",
                "clientOptions" => array("alias" =>  "email"),
            ));

Resources

Total 4 comments

#19335 report it
Vilo at 2015/05/23 08:46am
@PHP Senior Developer

Thank you.

#19320 report it
PHP Senior Developer at 2015/05/20 03:01am
Please make this module compatible with PHP 5.3

The module works well with PHP-5.3 but, with a customization.

The line:

if (in_array($key, ['oncomplete', 'onincomplete', 'oncleared', 'onKeyUp', 'onKeyDown', 'onBeforeMask',
                        'onBeforePaste', 'onUnMask', 'isComplete', 'determineActiveMasksetIndex']) && !$value instanceof CJavaScriptExpression) {

Should be changed to:

if (in_array($key, array('oncomplete', 'onincomplete', 'oncleared', 'onKeyUp', 'onKeyDown', 'onBeforeMask',
                        'onBeforePaste', 'onUnMask', 'isComplete', 'determineActiveMasksetIndex')) && !$value instanceof CJavaScriptExpression) {

As, array() declaration syntax of

$a = [2,3];

is not supported in PHP-5.3.

And it need to be

$a = array(1,2,3);
#18482 report it
Vilo at 2014/11/05 12:31am
@ Kartik V

Yes Kartik thank you, it inspired me, hats off to you and all the other yii staff for awesome framework.

#18476 report it
Kartik V at 2014/11/04 09:14am
Refer yii\widgets\MaskedInput in Yii2

Good effort on the extension (for Yii 1.x).

Hope you are aware - there exists an inbuilt yii widget MaskedInput based on the same jquery plugin - but this is for Yii 2.x.

Leave a comment

Please to leave your comment.

Create extension