In this tutorial, I will be showing you how you can add and use a third party custom field to better handle contact phone numbers. Trombinoscope Contacts Pro supports all standard custom fields out-of-the box and since version 4.2 you can also specify which third party fields you want to make available in your designs.
For this tutorial, you will need:
Step 1 - Download and install the Advanced Custom Fields from Tassos
This set of plugins extends the Joomla pool of fields with very useful and sophisticated ones. You can download them for free but getting the pro version will help the developer and give you even more useful fields!
Step 2 - Add a phone field to the Contact component forms
Go to Components -> Contacts. Go to Fields and create a new field. Select the ACF- Telephone type.
Setup the mask of the phone number. Here, we set it up so that any phone number will be looking like: (999) 999-9999.
Step 3 - Test the new field
Go to any of your contacts and enter information in the new phone field.
Step 4 - Enable support in Trombinoscope Contacts Pro
Go to System -> Global configuration -> Trombinoscope Contacts Pro, Shared options tab.
Select the custom field types you want to make available in the extension. For this tutorial, we add the ACF - Telephone custom field for better phone formatting.
The custom field is a phone number therefore we also want to be able to show it as a clickable icon on mobile devices (known as a link field in Trombinoscope Contacts)
Step 5 - Select the new field in any of the Trombinoscope Contacts menus or module instances.
From now on, you can add the new phone field to any of the menu items or modules instances of the Trombinoscope Contacts Pro extension.
The phone field is now also available for frontend edition. Learn how to edit contacts on a live site with the extension.
Step 6 - Create layouts for the phone field.
To show in contact cards or contact pages created with Trombinoscope Contacts Pro, the new field needs a layout that determines how the field output will look like. In this particular instance, it actually needs 2 layouts: one to show as regular field, one to show as a link field (where only the icon is clickable).
Create overrides of the Trombinoscope Contacts Pro layouts
Assuming you don't have previous overrides for the extension's layouts, go to Extensions -> Templates -> Styles and enter the template's customization page.
Go to the Create overrides tab, layouts section.
Select com_trombinoscopeextended, then details.
Cleanup the overrides
Go to the Editor tab, go to html -> Layouts -> com_trombinoscopeextended -> details.
Remove all layouts except tcp_detail_phone and tcp_icondetail_phone. Rename those files to tcp_detail_jfield_acftelephone and tcp_icondetail_jfield_acftelephone (the latest is used for icon-only link fields). It is always better to remove the overrides that you don't intend to modify (overrides are NOT updated when extensions are).
The naming convention is simple when adding third party custom fields layouts: use the name of the field's plugin. To determine the name to use, go to Extensions -> Plugins and search for the fields type.
Overriding the details layouts is just one way of adding your new field layout(s) to the extension. In this particular case, it was easier to use the phone layouts already available in the extension as a starter (since our new field is also a phone number). Usually, copying and modifying the generic layout is the way to go.
Test the layouts
In one menu instance of Trombinoscope created previously, we set the new field and check it's output. Without the layout(s), no phone number will show on the cards, despite the field being selected.
From now on, all phone fields will be formatted uniformly across the site, no matter where phones are edited or shown.
It is possible to use additional data in the layouts you have created. For instance, you may want to use some of the parameters of the field or even transform the original values.
Add the lines:
$field_id = $displayData['field_id'];
$field_values = $displayData['field_values'];
$field_params = $displayData['field_params'];
to access additional data.
$field_idis the field id,
$field_valuesis an array of the field values,
$field_paramsis an object containing the parameters specific to the field.
$field_params->click_to_call will give you the value set for the ACF - Telephone field 'Click-to-Call Link' option.