How can I add a mask to format a form input?

The MeioMask library has very little documentation so this FAQ is mostly written from trial and error and may not be complete or correct!

Install the library on your site

<?php
JHtml::_('behavior.framework', true);
$doc =& JFactory::getDocument();
$url = JURI::root().'components/com_chronoforms/extras/meio_mask/';
$doc->addScript($url.'Meio.Mask.js');
$doc->addScript($url.'Meio.Mask.Extras.js');
$doc->addScript($url.'Meio.Mask.Fixed.js');
$doc->addScript($url.'Meio.Mask.Regexp.js');
$doc->addScript($url.'Meio.Mask.Repeat.js');
$doc->addScript($url.'Meio.Mask.Reverse.js');
?>

The built-in masks

Fixed

• Brazilian Phone [Phone]: '(99) 9999-9999'
• US Phone [PhoneUs]: '(999) 999-9999'
• Brazilian CPF [Cpf]: '999.999.999-99'
• Brazilian CNPJ [Cnpj]: '99.999.999/9999-99'
• Date [Date]: '3d/1m/9999'
• US Date [Dateus]: '1m/3d/9999'
• Brazilian CEP [Cep]: '99999-999'
• Time [Time]: '2h:59'
• Credit Card [Cc]: '9999 9999 9999 9999'
• MAC address [Mac]: 'HH:HH:HH:HH:HH:HH'

As you may have noticed, Fábio Miranda Costa is Brazilian: CPF is a personal tax code; CHPJ a corporate one; and CEP a postcode.

Regexp

The Regexp library builds masks using Regular Expressions which are more flexible, but can be more complex to build. There are just three built in masks: IP address [ip], IPv6 address [ipv6] and Email [email].

Repeat

The Repeat library provides a set of masks that limit the kind of character that is allowed and the number of times it can be repeated. So, for example you call set H and 7 to set a mask of seven Hexadecimal characters.

The available characters 'kinds' are:

• z: a-z
• Z: A-Z
• a: a-zA-Z
• *: 0-9a-zA-Z
• H: 0-9a-fA-F
• @: 0-9a-zA-ZçáàãâéèêíìóòõôúùüñÇÁÀÃÂÉÈÊÍÌÓÒÕÔÚÙÜÑ
• h: 0-9 max 23
• d: 0-9 max 31
• m: 0-9 max 12
• 1: 0-1
• 2: 0-2
• . . .
• 9: 0-9

<input name='time' type='text' data-meiomask='fixed.time' />

<input name='repeat' type='text' data-meiomask='repeat' data-meiomask-options="{mask: '4', maxLength: 8}"  />

Unfortunately the current version of ChronoForms doesn't make it easy to add data attributes to form elements in the Form Wizard (unless you use the Custom Element element and add your own HTML).

Fortunately there are some other methods that we can use using JavaScript to add the validations.

If you just have a few validations to apply then you can attach them individually to inputs. Please first add a unique id to each element (in most cases this can be the same as the element name e.g. amount). Then to mask an input we can use a Load JS action and add JavaScript like this to mask the input as a US formatted number with two decimal places:

window.addEvent('domready', function() {
  $('amount').meiomask('Reverse', 'DecimalUs');
});

Note: the first and last lines only needed to be used once to wrap all of the JavaScript in a Load JS action. We'll leave it out of the following examples.

Or if we want to add a US$ prefix we can use this version:

window.addEvent('domready', function() {
  $('amount').meiomask('Reverse', 'DecimalUs');
});

Or we can use a third parameter to set a custom option for this Mask:

window.addEvent('domready', function() {
  $('amount').meiomask('Reverse', 'DecimalUs', {symbol: '£'});
});

These three parameters: the Mask Library, the Mask Preset and the Mask Options let us define a wide range of masks. There  is more about the Mask Options in the next section.

If you have several elements in your form that you want to format the same way for example, a group of amount elements, then there is a short-cut way to add Masks. You need to add a class to each element in the group like, say, 'dollar_amount'. Then JavaScript like this can add the same Mask to all of the elements with this class set.

window.addEvent('domready', function() {
  $$('input.dollar_amount').each(function(item) {
    $(item).meiomask('Reverse', 'Dollar');
  });
}); 

Meio Mask options

We've seen a couple of examples of setting Mask Options, in this section I've added a list of the available options that I have found.

See the sections above for examples of setting options. 

Fixed

The Fixed library has four options:

• autoSetSize: defaults to false; I'm not sure what it does
• placeholder: defaults to '_'; sets the 'placeholder' character where data will be entered e.g. __:__ for time
• removeIfInvalid: defaults to false; removes the value onblur if the input is not valid
• removeInvalidTrailingChars: defaults to true; cleans up any extra input

Regexp

This library only has one option regexp: which sets the regular expression to use.

Repeat

• mask: defaults to an empty string; see the section above for allowable 'kinds'
• maxLength: defaults to 0 which sets no limit; enter an integer to set a maximum length

Reverse

Creating custom masks

The examples above showed how to use the preset masks and also how to use the options parameter to over-ride the default options for that preset. You can also create new masks with your own preferred options using the createMask class.

Reverse

Here's an example of a new Reverse library mask: 

Meio.Mask.createMasks('Reverse', {
  'Adollar': {
    precision: 0,
    maxLength: 10,
    symbol: '$',
    thousands: ','
  }
});

The first line Meio.Mask.createMasks('Reverse', { tells Meio Mask that this is a new Mask using the Reverse library.

The next line sets the name for the new Mask 'Adollar' in this example.

The remaining lines specify the options for this mask: it has no decimal places; uses a comma as the thousands separator; shows '$' as the symbol and allows 10 characters - as this includes the separators the maximum amount is 99,999,999.

Once this Mask is defined we can apply it in exactly the same way as the preset masks:

$('input_name').meiomask('reverse', 'Adollar'); 

Regexp

Here's another example, this time for a Regexp library mask, the mask is for a British VAT (sales tax) number which has is a 9 or 12 digit number with an optional GB prefix. 

Meio.Mask.createMasks('Regexp', {
    'VatGB': {regex: /^(GB)?([0-9]{9}([0-9]{3})?|[A-Z]{2}[0-9]{3})$/}
});

As before, once the mask is created you can use it with any text input:

$('input_name').meiomask('regexp', 'VATGB'); 

Note: see the Regular Expression Library at RegExpLib.com for many more useful examples of regular expressions that you can use or adapt.