Module Phone Number Fieldtype

[adrian]

Phone Number Fieldtype 

 

A new fieldtype to enter phone numbers with 4 integer values for country, area code, number and extension and format the output based on predefined or custom options.

 

StyledOutput

 

The most common usage option will be: 

echo $page->fieldname //eg. +1 (123) 456-7890 x123

This provides a fully formatted phone number, based on the output format chosen from module's configuration page, or with the format override option (if enabled), when entering a phone number on a page.

 

This is a shortcut that produces the same output as: 

echo $page->fieldname->formattedNumber //eg. +1 (123) 456-7890 x123

Alternate styled options are:

echo $page->fieldname->formattedNumberNoExt: //eg. +1 (123) 456-7890
echo $page->fieldname->formattedNumberNoCtry: //eg. (123) 456-7890 x123
echo $page->fieldname->formattedNumberNoCtryNoExt: //eg. (123) 456-7890

echo $page->fieldname->unformattedNumber: //eg. 11234567890123
echo $page->fieldname->unformattedNumberNoExt: //eg. 11234567890
echo $page->fieldname->unformattedNumberNoCtry: //eg. 1234567890123
echo $page->fieldname->unformattedNumberNoCtryNoExt: //eg. 1234567890

Of course the actual output is determined by the selected format output

 

 

Raw Output

 

You can output the values for the component parts of the phone number like this:

echo $page->fieldname->country;
echo $page->fieldname->area_code;
echo $page->fieldname->number;
echo $page->fieldname->extension;

 

 

Output for mobile compatibility

 

To get iOS and other mobile platforms to recognize numbers and be able to automatically dial them, use something like this:

echo '<a href="tel:+'.$page->fieldname->unformattedNumberNoExt.'">'.$page->fieldname->formattedNumber.'</a>';

 

Selectors for searching

 

The component parts can be used in selectors like this:

$pages->find("phone.area_code=123");

Field Settings

 

There is a field settings for the width of the inputs in pixels.

 

There is a field settings for the width of the inputs in pixels.

 

You can also choose whether to display the country and extension fields for input. Off by default.

 

There is an additional checkbox that determines whether there is an option to override the default format option on a per entry basis, which will be useful when styling phone numbers from different countries on the one website. Off by default.

 

 

Custom formatting options

 

On the module's configuration page you can choose from predefined formats, or create custom formats using syntax like this:

 

{+[phoneCountry] }{([phoneAreaCode]) }{[phoneNumber,0,3]-}{[phoneNumber,3,4]}{ x[phoneExtension]}

 

which generates: +1 (123) 456-7890 x123

• Each component is surrounded by { }
• The names of the component parts are surrounded by [ ]
• Two comma separated numbers after the component name are used to get certain parts of the number using php's substr function, allowing for complete flexibility.
• Anything outside the [ ] is used directly: +,-,(,),x, spaces, etc - whatever every you want to use.

 

There are lots of complicated rules around numbers changing when dialed from different locations. A simple example is for Australia. When dialing from within Australia, area codes start with a 0, but when dialing from another country, the 0 must be omitted. You can write a simple format to handle this. The following truncates the first number from an Australian two digit area code:

{+[phoneCountry] }{([phoneAreaCode,1,1]) }{[phoneNumber,0,4] }{ [phoneNumber,4,4]}{ x[phoneExtension]}

 

which generates: +1 (7) 1234 5678 x123 even though the full "07" is stored in the area code field.

 

 

Where to get

 

Available from github:

https://github.com/adrianbj/FieldtypePhone

 

And the modules directory:

http://modules.processwire.com/modules/fieldtype-phone/

 

 

To Do

 

Need to increase the number of pre-defined formats. There seem to be so many options and no real standards, so I thought rather than create a huge list of options that no-one will use, I thought I'd wait and get you guys to contribute them as you need them. Either post your formats here, or send me a PR on github and I'll add them.

 

 

How to install

 

Download and place the module folder named "FieldtypePhone" in: /site/modules/

 

In the admin control panel, go to Modules. At the bottom of the screen, click the "Check for New Modules" button.

 

Now scroll to the FieldtypePhone module and click "Install". The required InputfieldPhone will get installed automatically.

 

Create a new Field with the new "Phone" Fieldtype.

 

Choose a Phone Output Format from the details tab.

 

Acknowledgments

 

This module uses code from Soma's DimensionFieldtype and the core FieldtypeDatetime module - thanks guys for making it so easy.

[adrian]

I was initially thinking about storing a formatted number as an extra field so you could simply do:

$page->fieldname->formatted_number, but for the sake of flexibility and reducing database redundancy, I went with leaving the formatting to the output. Any thoughts on this?

 

Now I am thinking that maybe I could go with something like the datetime field type's Output Format options and set up a few common formats to choose from as the default output, or the ability to define a custom output format in the field's details tab. This has been done and is now described in the initial post above.

 

Maybe getting carried away now , but also thinking about detecting the end user's country and determining whether the country code needs to be added to the front-end output or not.

 

Any thoughts / ideas?

[apeisa]

Nice work Adrian. I would definitely add formatted option too. Btw: is that how you you format phone numbers in US? Here phone numbers look like this +358 4143 8399 1 (not sure about spaces). Maybe allow few runtime options for different localizations?

[adrian]

I haven't updated the code in the modules directory yet, but take a look at the attached screenshot.

I have set up custom formatting options, similar to the way the DateTime output formatting options work. The user can choose from some pre-defined options, or edit an existing format to output as they want.

So now you can choose an output format and then output the formatted phone number on the front-end with:

$page->fieldname->formattedNumber

or you can manually format by using the component parts as described in the initial post above.

The formatted version is generated on the fly and not stored in the database.

Now I am wondering how many predefined formats I should set up. There are quite a lot of different formats, but not sure that there are any official standards: http://en.wikipedia.org/wiki/National_conventions_for_writing_telephone_numbers

Anyone out there an expert on phone number formats, or have any strong thoughts/ideas on this?

Also, does anyone have any comments on the format code syntax I set up, which you can see in the screenshot. Does this seem intuitive? Any other ideas?

I might attach the revised code here soon and ask for some feedback before updating it on github/module directory.

One more thought - wonder if it might be useful to have a format over-ride option - an extra subfield that allows page specific formatting of a phone number - might be useful for example for an international business with office around the world to be able to apply different formats on different pages.

Thanks 

[Manfred62]

here are some infos about telephone numbers. There are a lot of formats...

http://en.wikipedia.org/wiki/National_conventions_for_writing_telephone_numbers

[kongondo]

You are right. There are no international standards. I would go for formats that can be parsed by smartphones (iphone ex.), Skype (click to call), etc. as defaults and have the override/custom format as an option. 

Good job Adrian!

FYI

http://www.countrycallingcodes.com/iso-country-codes/

http://countrycode.org/

http://www.nationsonline.org/oneworld/countrycodes.htm

[lpa]

There seems to be standard or recommendation from ITU called E.123: Notation for national and international telephone numbers, e-mail addresses and web addresses in http://www.itu.int/rec/T-REC-E.123-200102-I/en. I doubt it is though used in every country.

[adrian]

OK, the predefined and custom formatting options have been added and pushed to github / modules directory. Lots of changes - I have updated the first post to reflect these.

If by chance you have started using this already, it might pay to delete any existing fields and recreate them. Not sure if there will be issues or not, but I had to change the db field type from "int" to "char" so it could handle leading zeros.

Would really appreciate a code review from those more experienced in module development to see if there is anything I could have done more efficiently.

[ryan]

Adrian, it looks to me like you've done a beautiful job coding and documenting this module–nice work! I really like what I see here. I had once starting building a phone Fieldtype and gave up after discovering the crazy number of formats out there. So lots of respect to you for sticking with it and producing something complete and very well done here. Here are my only suggestions (minor): 

• It might be nice to add a __toString() method to your Phone class, so when someone does "echo $page->phone"; they get a formatted (default) string. 
• I'm thinking the country and extension inputs may not be applicable to all potential users–maybe there could be a way to turn them off?
• Related to input again, it's a little unusual (in my locale) to split out the components of phone numbers into separate fields. Though the coder side of me likes that you've done that here. But wonder if there might be some alternate input option that lets you populate it in one field and have a processInput that separates it out into the parts with a preg_split('/[^\d]/', $phone) or something. 

[adrian]

Hey Ryan,

Thanks for the great feedback. I have incorporated the first two of your suggestions:

• $page->phone now generates the same as $page->phone->formattedNumber
• The country code and extension input fields are disabled by default, but can be enabled from the field's Input tab

I am not really sure how to make your last suggestion work consistently. Given the large variety in the number of digits in phone numbers around the world, I don't know how I could reliably parse a number entered in one field. How would I know what digits to separate out into which of the subfields? It would be do-able if they always entered in the same format - eg a space between each component of the number, but I think it might cause more problems than it solves. Do you have an idea I am missing?

I have also added a few new features:

• Ability to define an override format when filling out a phone number - I thought this might be useful for organizations with international offices where they want to format different phone numbers on their web site using different local formats. This option is off by default, but can be enabled on the Field's Input tab.
• Ability to edit all the formats available from the format selector, along with comments at the end of each entry. This was needed to make feature 1 work so the developer can define multiple custom formats without modifying the module's core code. This is found on the Field's Details Tab.
• Ability to change the numbers used in the formatted examples in the format select dropdown. I thought this would also be useful for international users so that they could make the numbers look more familiar - eg Australia has two digit area codes that always start with a '0'. This is found on the Field's Details Tab.

One issue I am having with new feature 3 is that I can't seem to store values with leading zeros in the input field config field (ie the values in the data field of the "fields" table). I haven't yet dug into the source code to see where the leading zero is being removed - any ideas how I can solve this? Ok, I see the problem is in the core wireEncodeJSON function. Only trouble is I am not sure how I can override this since I am not actually calling it directly.

EDIT: Also wondering if I should maybe move the Phone Output Format Options and Example Number Options to the modules config settings, rather than for the field. Obviously reduces flexibility, but simplifies setup. Any thoughts? As a side advantage, it would seem that it would allow me to solve the (int) problem mentioned above because I could hook into saveModuleConfigData (http://processwire.com/talk/topic/1849-clearing-cache-on-module-save/). I don't seem to be able to find a way to hook into the saving of ConfigInputfields - is that possible?

I am going to attach the revised version here for the moment. I would really appreciate your feedback before I update the code on Github and update the docs. I am worried that I might have overcomplicated things with all these new options.

Thanks!

InputfieldPhone.module

FieldtypePhone.module

[ryan]

I am not really sure how to make your last suggestion work consistently. Given the large variety in the number of digits in phone numbers around the world, I don't know how I could reliably parse a number entered in one field. How would I know what digits to separate out into which of the subfields? It would be do-able if they always entered in the same format - eg a space between each component of the number, but I think it might cause more problems than it solves. Do you have an idea I am missing?

I agree with you on this. It would be tricky and problematic. You'd have to enforce use of separators, likely both client side and server side. Having them split in two fields is a way of doing that already, while eliminating the possibility of errors. It does make it harder to enter and/or paste in a phone number, but it's ultimately more bulletproof. 

One issue I am having with new feature 3 is that I can't seem to store values with leading zeros in the input field config field (ie the values in the data field of the "fields" table). I haven't yet dug into the source code to see where the leading zero is being removed - any ideas how I can solve this? Ok, I see the problem is in the core wireEncodeJSON function. Only trouble is I am not sure how I can override this since I am not actually calling it directly.

I can update the logic of the wireEncodeJSON function to detect a 0-prepended string, but that won't help with past versions. Since you aren't calling wireEncodeJSON yourself, I'd suggest maybe prepending something uncomming to your format before the 0 (like a "~") and trim()'ing it out when using it. Silly I know, but I can't think of another way around that short of requiring a specific version of PW. 

EDIT: Also wondering if I should maybe move the Phone Output Format Options and Example Number Options to the modules config settings, rather than for the field. Obviously reduces flexibility, but simplifies setup. Any thoughts?

That might make sense, as I'm thinking an individual installation will probably want to standardize on one format rather than revisiting it for each field. 

Thanks for your updates, I am going to download now!

[ryan]

 I am worried that I might have overcomplicated things with all these new options.

While true that you've got a lot of options there (and perhaps more than most people need), I don't think it interferes with the regular use of the module either. Testing it out here, all seems to work nicely and didn't present any configuration challenges. While I didn't need the ability to define custom formats just yet, it's always nice to know that I can. 

[adrian]

Thanks Ryan,

I have just updated the module on the module's page with v1.0.3.

This version moves many of the settings to the module configuration page, rather than on a per field basis. I dealt with the leading zero issue by appending a tilde on settings save and removing it when loading the settings, so it is transparent for the user.

I have also update the instructions in the first post above.

If anyone has any changes they'd like to see, please let me know.

[landitus]

Hi adrian! Great module! I'm trying to use this field with FormBuilder and I'm having weird errors. When submiting the form I get an error:

Notice: Trying to get property of non-object in [route]/www/site/modules/FieldtypePhone/InputfieldPhone.module on line 140

Have you tested it with Form builder? Is it compatible?

[adrian]

landitus,

I haven't tested with FormBuilder (I don't have a copy). The "error" is just a php notice. Even though I can't seem to reproduce it in normal use, I think it's just needs another check to make sure $value->$key is set. Regardless, it shouldn't stop the module from working. Is the formatting actually working for you when you output the results of the form somewhere? 

[peterfoeng]

Hi Adrian,

Module apart, what theme are you using in your screenshot?

[adrian]

Moderna:

http://modules.processwire.com/modules/moderna/

Although with all the new additions that Ryan has developed for the new default theme for the dev version of PW, I am now just using the default theme.

[kixe]

Thanks for a useful module. I am using it for a german/ european website. I added two output format options:

{+[phoneCountry] }{[phoneAreaCode] }{[phoneNumber]}{-[phoneExtension]} /* Germany DIN5008, 'phone Extension' ≙ 'Durchwahl'*/
{+[phoneCountry] }{[phoneAreaCode] }{[phoneNumber]}{[phoneExtension]} /* International Telecommunication Union, ITU E.123  */

[adrian]

kixe,

Thanks for sharing those - I'll add them to the module, but I do have a question about the ITU E.123 format. It seems strange to me to have the extension appended directly to the number like that. I don't honestly know that much about phone number formats, but I took a quick read of this document:

http://www.itu.int/rec/T-REC-E.123-200102-I/en

and the key thing I got from it regarding extensions was:

To show an extension number of a PABX without direct in-dialling, the nationally used 

word or abbreviation for "extension" should be written immediately after the telephone numbers and 

on the same line as the word "telephone", followed by the extension number itself. 

 

Example 2: Telephone international +22 607 123 4567 ext. 876 

 

Any chance you could explain to me the difference between this and the format you have composed, which would output:

+22 607 1234567876 

 

Thanks

[kixe]

Adrian,

sorry but cannot help. Picked the Information I posted from somewhere in the net. The german Version is the usual/common one.

Another thing:
A customer (Safari on Mac) said in the phone field appears a comma, like a thousands separator, without putting it in before. I couldn't reproduce it on my computer. Did somebody else recognize this?
Problems with number_format or local settings? Any other ideas?

Thanks

[adrian]

I can't replicate the comma issue here either, but I am guessing it is something to do with the number formatting settings on their OS or in Safari specifically.

I have a couple of solutions for you try with your customer.

In InputfieldPhone.module on Lines, 75, 80, 84, 89 can you try the following.

Firstly, add:

pattern="[0-9]*"

to each of the input tags.

If that doesn't work, try changing the input type from "number" to "tel"

tel makes most sense here, but according to: http://www.w3schools.com/html/html5_form_input_types.asp it isn't supported by any browsers yet. Sounds like it might avoid the issue anyway, because the lack of support at least means that Safari won't think it's a number and try to add the comma.

Let me know if either of these work and I'll make the changes to the module.

[kixe]

Yes, I have read something similar in stackoverflow. I will do some tests. Maybe input type=text combined with the pattern you suggested is the safest way.

[NorbertH]

Hi There

Using Processwire : 2.5.10 (in Debug mode, but same happend with error reporting turned on for the server)

Module version : 1.0.6

i get several error notices when saving a field of this fieldtype:

Notice: Undefined index: output_format in /home/p4a/domains/009.pw4all.org/public_html/site/modules/FieldtypePhone/InputfieldPhone.module on line 45

Notice: Undefined index: output_format_options in /home/p4a/domains/009.pw4all.org/public_html/site/modules/FieldtypePhone/InputfieldPhone.module on line 46

Notice: Undefined index: example_country in /home/p4a/domains/009.pw4all.org/public_html/site/modules/FieldtypePhone/InputfieldPhone.module on line 47

Notice: Undefined index: example_area_code in /home/p4a/domains/009.pw4all.org/public_html/site/modules/FieldtypePhone/InputfieldPhone.module on line 48

Notice: Undefined index: example_number in /home/p4a/domains/009.pw4all.org/public_html/site/modules/FieldtypePhone/InputfieldPhone.module on line 49

Notice: Undefined index: example_extension in /home/p4a/domains/009.pw4all.org/public_html/site/modules/FieldtypePhone/InputfieldPhone.module on line 50

This is pretty annoying ...

[adrian]

The problem is that you haven't selected a "Phone Output Format" in the module config settings. The module needs this to know how you want it formatted.

Do that and the errors will go away !

That said, I should probably handle this better

[adrian]

Actually, I take that back - having "None" selected is a valid option as you can choose to output the components manually. 

For now, all you need to do is save the module config settings page once and the errors will go away, but I will fix the module so this is not necessary - should have it done pretty quickly.

EDIT: Updated version of module just committed now saves default config settings during installation.