How many ways can you turn a field into a phone link in AppGini?

So many users tell us how much they like the hooks feature in AppGini. It allows almost unlimited ways to customize the generated AppGini apps; changing appearance, adding features, pages, rapid workflows, … etc. In fact, users really surprise and amaze me with the very creative things they do using hooks.

Due to the power and so many possibilities, however, hooks could sometimes feel overwhelming. There are lots of ways to do customizations. I’m trying to tackle that issue in this post. Let’s take as an example the phone field from the Customers table of the Northwind demo.

The basic idea in order to make the phone number a “dialable” link is to convert the HTML of the phone number from this:

123456789

to this:

<a href="tel:123456789">123456789</a>

This changes the phone number into a clickable link like this 123456789 that opens the phone dialer if you’re viewing the page on a mobile or tablet.

How many ways can this be done?

Turns out there are several ways to do this in AppGini. You could do it server-side through a mix of PHP and SQL code, or server-side through PHP and JavaScript, or client-side through JavaScript. There is even a pure SQL-only way that we’ll also discuss.

Before we begin our customization, let’s first configure the field in AppGini to display as text-only (no link) in the table view. This would make life much easier later!

Method 1: server-side PHP+SQL using tablename_init hook

This method modified the SQL query used to display the data of the table view. We want to format the phone field as an HTML dialer link. To do so, we need to edit the generated hooks/customers.php file (change customers to the actual table name in your case). We’ll change the code of the customers_init() hook like this:

function customers_init(&$options, $memberInfo, &$args){
  $options->QueryFieldsTV = array_merge(
    $options->QueryFieldsTV, 
    ['`customers`.`Phone`' => "CONCAT('<a href=\"tel:', `customers`.`Phone`, '\">', `customers`.`Phone`, '</a>')"]
  ); 
  return true;
}

The code above would modify the portion of SQL for the Phone field to display as a dialer link.

Method 2: client-side JavaScript in tablename-tv.js

This method involved modifying the phone text in the browser (client-side) using jQuery. We need to edit the hooks/customers-tv.js file (we should create that file if it’s not already there) like that:

$j(function() {
  $j('td.customers-Phone').each(function() {
    var cell = $j(this), phone = cell.text().trim();
    cell.html('');
    $j('<a href="tel:' + phone + '">' + phone + '</a>').appendTo(cell);
  })
})

In the code above, we’re doing these steps for each phone cell in the table view:

1. Retrieve the phone number from the cell.
2. Empty the cell.
3. Add a dialer link to the emptied cell using the phone number we retrieved in step 1.

Not quite as easy as method 1 maybe, but we’re demonstrating the various ways we could achieve our requirement 🙂

Method 3: client-side JavaScript in footer-extras.php or header-extras.php

Another way to modify the phone field via JavaScript is to edit the hooks/footer-extras.php or hooks/header-extras.php file (editing only one of them is sufficient). The code would look exactly the same as method 2 above, except that we should wrap it inside a <script> tag, like this:

<script>
  $j(function() {
    $j('td.customers-Phone').each(function() {
      var cell = $j(this), phone = cell.text().trim();
      cell.html('');
      $j('<a href="tel:' + phone + '">' + phone + '</a>').appendTo(cell);
    })
  })
</script>

This would work the same as method 2, yet, again, we’re demonstrating another slightly different way of doing what we want to do. A tiny drawback of this method, however, is that the JavaScript code would be executed in all pages of our app (because header-extras.php and footer-extras.php files are included in all pages), but it will only take effect in the customers table view. This would add a minuscule performance hit that is very safe to ignore, yet it’s just worth mentioning.

Method 4: server-side PHP+JavaScript in tablename_header hook

In this method, we’ll again use the same JavaScript code used in methods 2 and 3 above, but we’ll inject it server-side using the customers_header hook in the hooks/customers.php file:

function customers_header($contentType, $memberInfo, &$args){
  $header='';

  switch($contentType){
    case 'tableview':
// --- our customization code goes here ...
      ob_start(); ?>
      <!-- same js code as methods 2, 3 above -->
      <script>
        $j(function() {
          $j('td.customers-Phone').each(function() {
            var cell = $j(this), phone = cell.text().trim();
            cell.html('');
            $j('<a href="tel:' + phone + '">' + phone + '</a>').appendTo(cell);
          })
        })
      </script>
      <?php
      $header = '<%%HEADER%%>' . ob_get_clean();
// --- end of our customization code.
      break;

    case 'detailview':
      $header='';
      break;

    case 'tableview+detailview':
      $header='';
      break;

    case 'print-tableview':
      $header='';
      break;

    case 'print-detailview':
      $header='';
      break;

    case 'filters':
      $header='';
      break;
  }

  return $header;
}

You could use customers_footer hook function instead. The code would be almost the same as above, except you should replace <%%HEADER%%> with <%%FOOTER%%>.

Yep, this is getting too complicated, I know. But we’re just showing one more method.

Method 5: SQL in dataFormats.cfg

This is perhaps the easiest way to do our requirement, and, as a bonus, it’s very easy to apply to multiple fields in multiple projects. Open the file C:\program files\AppGini\add-ons\dataFormats.cfg in a text editor (this path might var slightly based on where AppGini is installed on your PC) and append this line to the end:

Phone link; CONCAT('<a href="tel:', %%FIELD%%, '">', %%FIELD%%, '</a>')

Now, it’s very easy to format a field as a phone link in AppGini by selecting the field, going to the Data format tab, and selecting Phone link. No hooks needed 😀

One tiny caveat for this method: you should back up your customized dataFormats.cfg file before upgrading to a new version of AppGini to avoid overwriting your modifications. You should then re-apply your modifications to the new file after upgrade.

Summing up

As you see by now, AppGini hooks allow you to take many different approaches to achieve a modification. Each approach has its pros and cons. It’s up to you to choose the method you prefer. In this post I tried to compile as many methods into one place for you to compare them and decide which way to go. I hope you find it helpful 🙂