Jump to content
adrian

Phone Number Fieldtype

Recommended Posts

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.

post-985-0-50046000-1377903027_thumb.png

post-985-0-82117400-1378131916_thumb.png

  • Like 15

Share this post


Link to post
Share on other sites
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?

Share this post


Link to post
Share on other sites

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?

Share this post


Link to post
Share on other sites

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 

post-985-0-08138200-1378009655_thumb.png

  • Like 1

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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. 
  • Like 2

Share this post


Link to post
Share on other sites

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

  • Like 2

Share this post


Link to post
Share on other sites
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!

Share this post


Link to post
Share on other sites
 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. 

Share this post


Link to post
Share on other sites
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.
  • Like 2

Share this post


Link to post
Share on other sites

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?

Share this post


Link to post
Share on other sites

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? 

Share this post


Link to post
Share on other sites

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  */

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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.

  • Like 1

Share this post


Link to post
Share on other sites

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.

  • Like 1

Share this post


Link to post
Share on other sites

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 ...

Share this post


Link to post
Share on other sites

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 :)

  • Like 1

Share this post


Link to post
Share on other sites

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.

  • Like 1

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

  • Recently Browsing   0 members

    No registered users viewing this page.

  • Similar Content

    • By bernhard
      --- Please use RockFinder3 ---
    • By MoritzLost
      Cacheable Placeholders
      This module allows you to have pieces of dynamic content inside cached output. This aims to solve the common problem of having a mostly cacheable site, but with pieces of dynamic output here and there.  Consider this simple example, where you want to output a custom greeting to the current user:
      <h1>Good morning, <?= ucfirst($user->name) ?></h1> This snippet means you can't use the template cache (at least for logged-in users), because each user has a different name. Even if 99% of your output is static, you can only cache the pieces that you know won't include this personal greeting. A more common example would be CSRF tokens for HTML forms - those need to be unique by definition, so you can't cache the form wholesale.
      This module solves this problem by introducing cacheable placeholders - small placeholder tokens that get replaced during every request. The replacement is done inside a Page::render hook so it runs during every request, even if the response is served from the template cache. So you can use something like this:
      <h1>Good morning, {{{greeting}}}</h1> Replacement tokens are defined with a callback function that produces the appropriate output and added to the module through a simple hook:
      // site/ready.php wire()->addHookAfter('CachePlaceholders::getTokens', function (HookEvent $e) { $tokens = $e->return; $tokens['greeting'] = [ 'callback' => function (array $tokenData) { return ucfirst(wire('user')->name); } ]; $e->return = $tokens; }); Tokens can also include parameters that are parsed and passed to the callback function. There are more fully annotated examples and step-by-step instructions in the README on Github!
      Features
      A simple and fast token parser that calls the appropriate callback and runs automatically. Tokens may include multiple named or positional parameters, as well as multi-value parameters. A manual mode that allows you to replace tokens in custom pieces of cached content (useful if you're using the $cache API). Some built-in tokens for common use-cases: CSRF-Tokens, replacing values from superglobals and producing random hexadecimal strings. The token format is completely customizable, all delimiters can be changed to avoid collisions with existing tag parsers or template languages. Links
      Github Repository & documentation Module directory (pending approval) If you are interested in learning more, the README is very extensive, with more usage examples, code samples and usage instructions!
    • By Craig
      I've been using Fathom Analytics for a while now and on a growing number of sites, so thought it was about time there was a PW module for it.
      WayFathomAnalytics
      WayFathomAnalytics is a group of modules which will allow you to view your Fathom Analytics dashboard in the PW admin panel and (optionally) automatically add and configure the tracking code on front-end pages.
      Links
      GitHub Readme & documentation Download Zip Modules directory Module settings screenshot What is Fathom Analytics?
      Fathom Analytics is a simple, privacy-focused website analytics tool for bloggers and businesses.

      Stop scrolling through pages of reports and collecting gobs of personal data about your visitors, both of which you probably don't need. Fathom is a simple and private website analytics platform that lets you focus on what's important: your business.
      Privacy focused Fast-loading dashboards, all data is on a single screen Easy to get what you need, no training required Unlimited email reports Private or public dashboard sharing Cookie notices not required (it doesn't use cookies or collect personal data) Displays: top content, top referrers, top goals and more
    • By daniels
      This is a lightweight alternative to other newsletter & newsletter-subscription modules.
      You can find the Module in the Modules directory and on Github
      It can subscribe, update, unsubscribe & delete a user in a list in Mailchimp with MailChimp API 3.0. It does not provide any forms or validation, so you can feel free to use your own. To protect your users, it does not save any user data in logs or sends them to an admin.
      This module fits your needs if you...
      ...use Mailchimp as your newsletter / email-automation tool ...want to let users subscribe to your newsletter on your website ...want to use your own form, validation and messages (with or without the wire forms) ...don't want any personal user data saved in any way in your ProcessWire environment (cf. EU data regulation terms) ...like to subscribe, update, unsubscribe or delete users to/from different lists ...like the Mailchimp UI for creating / sending / reviewing email campaigns *I have only tested it with PHP 7.x so far, so use on owners risk
      EDIT:
      Since 0.0.4, instructions and changelog can be found in the README only. You can find it here  🙂
      If you have questions or like to contribute, just post a reply or create an issue or pr on github, thanks!
    • By MoritzLost
      Sorry for the convoluted title. I have a problem with Process modules that define a custom page using the page key through getModuleInfo (as demonstrated in this excellent tutorial by @bernhard). Those pages are created automatically when the module is installed. The problem is that the title of the page only gets set in the current language. That's not a problem if the current language (language of the superuser who is installing the module) is the default language; if it isn't, the Process page is missing a title in the default language. This has the very awkward effect that a user using the backend in the default language (or any other language) will see an empty entry in the setup menu:

      This screenshot comes from my Cache Control module which includes a Process page. Now I realize the description sounds obscure, but for us it's a common setup: We a multiple bilingual sites where the default language is German and the second language is English. While the clients use the CMS in German, as a developer I prefer the English interface, so whenever I install a Process module I get this problem.
      As a module author, is there a way to handle this situation? I guess it would be possible to use post-installation hooks or create the pages manually, but I very much prefer the declarative approach. The page title is already translatable (through the __ function), but of course at the time of installation there is no translation, and as far as I'm aware it's not possible to ship translations with a module so they are used automatically. Could this situation be handled better in the core? I would prefer if the module installation process would always set the title of the Process page in the default language, instead of the language of the current user.
×
×
  • Create New...