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:
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;
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;
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:
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;
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".
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.
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!