reportbuilder/Column Display Functions

Back to Index

In some cases you may want the data for a particular column to be transformed in some way before it is output to the page.

For example, the hidden column in the course table contains either a 0 (for visible) or 1 (for hidden). If you wanted to create a column that displays the visibility status to a user, it would be better for the column to contain the words 'Visible' and 'Hidden' rather than 0 and 1.

Display functions provide a way to achieve that, by preprocessing the column data prior to display.

Here's the column option required to display the course hidden column:

$this->columnoptions[] = new rb_column_option(
    'course',
    'hidden',
    get_string('coursevisibility'),
    'base.hidden',
    array('displayfunc' => 'course_visibility')
);

The array is an optional argument which lets you provide additional information about the column option. In this case we've passed a display function name, which will be used to modify the appearance of the column. Each column option can have its own display function, or you can reused the same function for similar columns.

You can name the display function anything you like, but when the column is displayed report builder will look for a function with the name 'rb_display_' followed by the name you choose. So in this case it will look for a function called 'rb_display_course_visibility'. If found, the report will be processed as follows:

• Instead of displaying a particular cell, the value from the database will be passed to the display function for that column (as the first argument)
• All the data for the current row will be passed as a second argument as an object
• Instead of displaying the value, the return value of the function will be displayed instead
• If the display function can't be found, the original data will be displayed unchanged
• The 3rd argument will be a boolean indicating if the report is being exported (to excel etc) in case you want to output different code when exporting)

You must define the display function as a method of the source: outside the constructor function but inside the source class definition. In this example the display function will look like this:

function rb_display_course_visibility($item, $row, $isexport) {
    if ($item === null) {
        // no value found, return an empty string
        return '';
    } else if($item == 0) {
        // the course is visible
        return get_string('visible');
    } else {
        // the course is hidden
        return get_string('hidden');
    }
}

It's important to note that although the appearance of the column has changed, any filters which are based on this column will still be comparing against the database value, not the display value. So a text filter for the word 'visible' would fail, because the database is still returning '0'.

If you want to create a display function that makes use of data from multiple columns see combining multiple fields.

There are a number of pre-defined display functions available to source creators. See predefined common options.

Formatting strings from the database

Prior to 1.1.10 it was the display functions responsibility to do any filtering on data from the database. From 1.1.10 onwards, report builder automatically passes the first argument through filter_string() to ensure multilang filters are applied. The 2nd argument is still raw from the database so any data from that object needs to be filtered.