[Article] A Global Phone Formatting Method

by Chris Cain
Extensitech

Last month, David Workman talked about abstract programming, in his Code Challenge. In this article, we’ll use those principles to create a global method that will format a phone number onDataChange.

Sometimes it seems that every user of our solutions has their own idea about how a phone number should be entered: 123.456.7890 or 123-456-7890 or (123) 456-7890. These are, of course, just American phone numbers; the issue is even more pronounced in solutions with international phone numbers, and multiple phone number schemes.

While this is hardly the end of the world, just the cosmetic aspects of this disparity can make your otherwise beautiful solution look amateurish. Consciously or not, your users will compare your solution to “cheaper” solutions like Outlook (which are funded by selling many millions of copies). If Outlook can automatically format a phone number, why can’t you?

There’s a practical problem here, too, in that users searching for a phone number need to allow for all the different formats…or all the ones they can remember.

The key here is that phone numbers will appear on many forms, and often in tabpanels. We don’t want to create a separate method for each and every occurrence of a phone number on a form. Instead, we’ll create one, global method that can be set as the onDataChange method anywhere in your solution, even in tabpanels!

Step by Step

Instead of just showing the whole method at once, we’ll go through each segment one at a time with a little commentary. This may make it a bit tougher to copy and paste, but really, each segment should be brought in and considered on its own. You may have good reason for changing any or all of these segments. While the method below works great for one of my clients, different solutions have their own challenges. By considering each segment, you’ll be able to see what each is doing, and see where to enter any modifications or enhancements you’d like to make for your own solution.

First, we want our method to determine ‘where’ the user is in our solution, since we not only want to capture what the user entered; we want to replace it with a properly formatted phone number.

// gather information about where the user is and what s/he entered
// first, get the form and element that triggered the method
var eleName = application.getMethodTriggerElementName();
var frmName = application.getMethodTriggerFormName();

// then use those to find the dataProvider name, from the database &
var fldName = forms[frmName].elements[eleName].getDataProviderID();

// and use that to get the contents of that dataProvider
var fldContents = forms[frmName].foundset.getRecord(forms[frmName].foundset.getSelectedIndex())[fldName];

So now, we know ‘where’ the data is, both in terms of the solution and the database. Next, let’s check to see whether there’s anything to format. If, for example, the user has just cleared the field, or entered “N/A”, we don’t want to insert any dashes or whatnot into the field. Also, we should allow some sort of ‘escape’ in case the user doesn’t want the phone number formatted, for some reason. For example, perhaps this is a special phone number like ‘911’ or ‘411’, or it’s in a country for which we’re not providing an appropriate format (more on that later). For your solution, there may be other reasons not to format, but we’ll start with these.

// exit if there's nothing in the field to format
if (!utils.stringToNumber(fldContents) || utils.stringLeft(fldContents,1) == '+')
{
    return;
}

In the next small segment, we declare the two variables that we’ll work with for formatting: the entry, and the format to use. The entry starts out as the contents of the field. The format replaces the numeric characters with ‘#’. In this case, for simplicity’s sake, we’re just using a hard-coded format, but you can easily imagine populating the variable with a preference field, or from a table of formats by country. We load this format into a variable called ‘phone’, because we’re going to morph that format into the actual formatted phone number.

// Set initial variables.
var entry = fldContents;
var phone = '(###) ###-####';

OK, so now, we’ll loop through the format (‘phone’) and replace the #’s with numbers from the entry.

// fill in the format pattern
while (utils.stringPatternCount(phone, '#')>0 && entry )
{
   if(utils.stringPatternCount('0123456789',utils.stringLeft(entry, 1)))
   {
      nextPosition = utils.stringPosition(phone, '#', 0, 1 );
      phone = utils.stringIndexReplace(phone, nextPosition , 1 , utils.stringLeft(entry, 1));
   }
   entry = utils.stringRight(entry, entry.length - 1);
}

So now we’ve filled in our format template, but what if there are numbers left over? For example, what if the user puts in “extension 55” or “x3”? We want to capture the text, such as “extension” or “x”, before getting the numbers after it. If the user didn’t give us any definition for the extra numbers, we’ll just put in a default “x”.

 // if there's more, fill in initial letters beyond the format, such as 'ext' or 'x'
if ( entry )
{
   if(utils.stringPatternCount('0123456789',utils.stringLeft(entry, 1)))
   {
      phone += ' x';
   }
   else
   {
      phone += ' ';
   }
}

Now we can add any leftover numbers:

// if there's still more, enter remaining numbers
if ( entry )
{
   phone += ' ';
}
while (entry)
{
   if(utils.stringPatternCount('0123456789',utils.stringLeft(entry, 1)))
   {
      phone += utils.stringLeft(entry, 1);
   }
   entry = utils.stringRight(entry, entry.length - 1);
}

And finally, our formatted phone number is complete in the ‘phone’ variable. All that remains is to put it back. Remember at the beginning, where we got the form name and the dataProvider name?

forms[frmName].foundset[fldName] = phone;

So now, anywhere a phone number field appears, we can set an “onDataChange” event to run this global method, and the phone number will be formatted properly.