Customizing the data displayed in the table view


Sometimes you may need to change the way data in one of your tables is displayed to users. Imagine this scenario: You have a rating field in one of your tables that takes a value between 1 and 5. Instead of displaying the rating, you want to show stars. Here is a screen shot of the table view showing the original data:

Default formatting of the table view fields.


And here is the table view after applying the desired data formatting. Notice that the Customer Ratings column now displays star ratings rather than numbers.

Customized formatting of the table view fields shows star ratings rather than numbers.


Note that we don't want to actually store the Customer Ratings field as an image in the database. We want to store it as numbers (1, 2, 3, .. etc) to make it easy to edit it, and just display it as stars for visitors. To do this, we need to use the tablename_init hook.

Using the tablename_init hook to apply custom field formatting

The tablename_init hook is called before executing the table view query and so we can use it to change that query to apply our desired formatting. Please refer to the tablename_init documentation for details on how it works.

In this example scenario, our table is called cameras. So, the hook file is named cameras.php and can be found inside the generated hooks folder. Let's open that file in a text editor and find the function named cameras_init. This is how it looks like initially:
function cameras_init(&$options, $memberInfo, &$args){
	
	return TRUE;
}
The $options variable is a DataList object that contains a lot of configuration parameters for the cameras table. To change the formatting of the table view fields, we need to edit the $options->QueryFieldsTV parameter. Here is the documentation of the DataList object if you want to learn more about other parameters of $options.

Let's modify the cameras_init hook to read:
In the above code, we're replacing the table view fields with new ones that enforce the desired data formatting. Since all we need to do is change the formatting of the ratings field (which is the field labeled Customer Ratings in the table view), we added a condition at line 8 to find that field.

On line 10, we created a new SQL formatting of that field that replaces the numbers stored in the field with images showing star ratings. The images are named 1.gif, 2.gif, ... etc. That way, we can easily make the replacement using the numerical value stored in the field as part of the image file name.

Here are the ratings images in case you need to use them in your own application. Line 10 above assumes they are placed inside the hooks folder. So, if you copy the above code to your own application, you should save the images to that folder as well. To download them, just right click on each of the images below and select to save the image.



Endless possibilities

You can use the same technique outlined above to apply almost any other formatting to the data. You can make for example unit conversions, ordering links or links to external websites, and a lot more.