How to customize EditableTables and Forms using input masks?

How to customize EditableTables and Forms using input masks?


Platform 9 brings new widgets, namely EditableTable and Form, which allow users to read and edit data across multiple devices and form factors. In order for end-users to easily understand that data, sometimes you need to format it in specific ways. The same applies when the user needs to edit data - the expected format should be obvious for your users. This is especially true for internationalization scenarios, in which having a wrong format can be a productivity and usability killer for end users.

We want to make sure applications have a great experience, so we went down a path to investigate how can we optimize input and display of information on your apps. The outcome brought us to a conclusion that using “input masks” is a great way to address this challenge. So we released CustomMasks an open source component - available here at the OutSystems Forge - that helps you with this. Let’s see how it works.

Imagine we have a list of orders with several details as displayed below. A product order will have a name, a unit price, and the date of purchase. To allow the end-user to easily find the price information, we want to add the currency symbol before the price value. Regarding the order date, depending on the nationality of the end-user, the standard date format can change. We want to display the information in the format the end-user is more familiar with - for instance, in the U.S., the most common date format is mm/dd/yyyy, but for Brazil you get something completely different such as dd-mm-yyyy.


You can check the following video of a customized EditableTable, and some other input masks that may be useful to you.


How does it work?

Consider the previous example of a list of orders, where you want to quickly switch between reading and editing rows for fast inline editing. The best widget for this scenario is the EditableTable (see here how to use EditableTables).

So after installing the CustomMasks component, let's format this data:

  1. Add a reference to the following web blocks in your module: MaskText, MaskNumber, MaskDate and MaskCurrency. All web blocks have one mandatory input parameter (InputID), which is the Id of the input widget you want to apply the input mask to;

  2. Format the price input using MaskCurrency: This web block has several optional input parameters to define the final mask. Some of the parameters will help the users read the data - like the prefix symbol ‘$‘ equivalent to the corresponding site property - while others will help in writing - such as how many decimal digits are allowed. Since this is a numeric input you are able to define the decimal and group separators, and for that you can use the corresponding site properties. By default dots are used to represent separate decimal and commas are used to separate groups;

  1. Format the date using MaskDate: This web block has an input parameter  called DateFormat which allows you to specify the format you want to use. This date format is defined by setting the order of the day (dd), month (mm) and year (yyyy), and also by setting the separator between them. For example, dd-mm-yyyy and yyyy/mm/dd are valid date formats. Note that you cannot use the RichWidget Input_Calendar and the MaskDate on the same date input, or you will get wrong and unexpected values.

The final result is a customized Editable Table with the desired date format and with a formatted price value - all in just a couple of minutes. Just drag the most suitable web block for your scenario, specify its input parameters according to your needs, and it’s done.


There are also other things you can achieve with this component:

  1. In scenarios where the input data is numeric and has boundaries - such as quantities or measures - the MaskNumber can be applied and you can restrict how many decimal digits the end-user can write;

  2. You can add additional restrictions to the data written by the end-user. For instance, a NIB value can only have 21 digits, so you can use a MaskText with a MaskDefinition "9999-9999-9999-9999-9999 9".

  1. There’s also an optional input parameter in the MaskText and MaskCurrency blocks that allow you to toggle between keeping the mask or not when the input data is send to the server. For instance, in the NIB value you may want to keep the separator ‘-’ when the value is send to the server. By default this parameter is set to true in MaskText. On the other hand, for the price value, you don’t want to send the currency symbol to the database. For that reason the parameter is set with false by default on the MaskCurrency block.

  2. The input parameter AdvancedOptions is available in all web blocks, and here you can specify other options like clearMaskOnLostFocus, which allow you to show the mask even when the input element doesn’t have focus. You will find more information about this in the component documentation.


Entering data is a hassle for users and inconsistent data is a pain for developers! Using input masks will address both of these pains: you’ll get better and more consistent data, and it will be a lot easier for your users to read and enter that data. And that’s what really makes a great application!

Hi Sara,

We want to use CustomMask with an EditableTable widget to display currency. However, some of the amounts will have a decimal part ending with 0 or 00 (e.g. € 2,50 or € 5,00). We can't seem to get CustomMask to display the 0s, showing "€ 2,5" etc. instead. Is there an easy way to make CustomMask display a currency with 2 decimals always?
I guess the answer is "no"?
Hello Kilian,

I think I found the problem but allow me to confirm with Sara first and we will get back to you ;)
Hi Rui,

That's good news! I'll be eagerly awaiting your update :).
Kilian Hekhuis wrote:
I guess the answer is "no"?
Hello Killian, sorry for the late answer! 
I'm aware of that issue and I think it is related with the unsmask and mask that is done when the value is submitted to the server. This is done in order to remove the currency symbol before the submit.
I will try to fix it as soon as possible, and I will let you know when a new version is available.

Thank you for use the CustomMask component :)
It's a great component, though it could use a few minor improvements, amongst which the above. Some other wishes of ours:
  • with MaskNumber, if the value is doesn't have decimals it doesn't show any decimals until you enter a decimal point/comma, even if you have specified DecimalDigits (so e.g. 6 stays six, but 6.0 becomes 6.00000);
  • with MaskNumber, there's no way to limit the number of digits before the decimal point. It would be swell to be able to limit those as well;
  • very minor, but at least in Chrome, when the input box gets/loses focus, the content moves a pixel (or two) to the left/right, which it shouldn't;
  • with MaskText, the place holder is always _ (underscore). It would be nice to be able to select the placeholder character;
  • the component CustomMask is based on also has a RegEx version. It would be great if that one became available too.
Well, that's it, of the top of my head. If you ever get bored and lack something to do, think of the above bullets :).

Great feedback! Thank you for sharing :)
I will add it to my todo list!
Hi Sara,

Some more feedback: I have a text input box that I bind to a decimal, and use MaskNumber to make it have a decimal comma instead of a dot. If I have a button with Method Submit (but not Ajax Submit!), the bound decimal is 0.0 in the Destination screen action. I'm not sure whether this is a bug of the component or a bug of the platform, but it's rather annoying...