Advanced column options

Overview

While the adding a column page describes the minimum information you must provide to generate a column option, there are a number of additional options you can set to change the columns behaviour as described below. Optional parameters are provided via an associative array passed as the 5th argument to rb_column_option().

Prevent column sorting

By default columns can be sorted (alphabetically or numerically), by clicking on the column heading (once to sort ascending, click again to switch direction). If it doesn't make sense to sort the column (for instance a column that contains a picture), you can set the nosort flag as follows:

new rb_column_option(
    [type],
    [value],
    [name],
    [field],
    array(
        'nosort' => true
    )
);

Exclude column from export files

Some columns may be useful in a report when displayed as a webpage, but are not needed when the report is exported. For example, your report may include an options column that lets a user perform actions on each row. To prevent it from appearing in the export file, set the noexport flag:

new rb_column_option(
    // first 4 arguments here
    array(
        'noexport' => true
    )
);

Adding style to columns

Each column in a report is assigned a class according to its type and value, in the format 'type_value'. So each cell of the course fullname column will have 'class="course_fullname"' added. This makes it possible to use CSS to directly style a particular column. If you want to apply style to the column directly another option is to set the 'style' parameter:

rb_column_option(
    // first 4 arguments here
    array(
        'style' => array(
             'color' => 'red',
             'font-weight' => 'bold'
        )
    )
);

The above statement would add 'style="color:red; font-weight: bold;"' to each cell in the column.

Hidden columns

Report builder reports include a show/hide column functionality which allows the user viewing the report to remove columns from the report to only show the columns that interest them. This is separate functionality from the 'columns' table in a report settings, the user can only choose to show/hide the columns defined by the Site Administrator.

By default, all columns chosen by the administrator are shown, and the user can choose to hide one or more columns with the show/hide button. However, if you set the hidden parameter on a column option, the column will be hidden from users by default, but still available to the user if they show it via the show/hide button.

rb_column_option(
    // first 4 arguments here
    array(
        'hidden' => 1
    )
);

Note this behaviour is different from the normal 'hide' feature, e.g. hide courses, which prevents users from seeing the course at all. In report builder the hidden column is available to the report's user, just not by default.

Hidden columns are still loaded each time the report is displayed, so in most cases it makes sense to just carefully select the desired columns or create two or more reports, rather than including a large number of hidden columns.

Show columns by capability

The 'capability' parameter allows you to selectively show a particular column based on a capability in the system context. This is most commonly used to show a particular column when the report is viewed by a Site Administrator but hide it from other users:

rb_column_option(
    // first 4 arguments here
    array(
        'capability' => 'moodle/site:doanything',
    )
);

As defined above, this column would only be visible to users with the 'moodle/site:doanything' capability set in the system context.

Default headings

By default, when a new column is added to a report, the column heading will be the same as the name of that column option. In some cases that might not be the most sensible heading name, so you can set 'defaultheading' to override what is shown. For example:

rb_column_option(
    'course',
    'namelink',
    'Course name (linked to course page)',
    'base.fullname',
    array(
        'displayfunc' => 'link_course',
        'extrafields' => array('courseid' => 'base.id'),
        'defaultheading' => 'Course name'
    )
);

In this case, had we not included 'defaultheading', adding this column would have used 'Course name (linked to course page)' as the column heading. Now instead it will just use 'Course name'.

Unselectable columns

There is a property called 'selectable' that is set to true by default. If instead you set it to false in your column option definition:

rb_column_option(
    'org',
    'path',
    'Organisation path',
    'organisation.path',
    array(
        'selectable' => false,
    )
);

The column will not appear in the column option selector in the user interface, essentially making it unavailable for users to choose.

This is useful if you need a particular column to filter against, but it's not something that is useful to end users. A good example is the 'path' field in hierarchies - it is needed to make the hierarchy items filter work but wouldn't be something you'd want to display in the column options pulldown as it may confuse users.

Other parameters

The 'joins' parameter has been previously discussed on the A basic join page. It accepts either a string containing the name of a join, or an array of join names if multiple joins are required.

The 'displayfunc' parameter is described on the Column display functions page.

The 'extrafields' parameter is described on the Combining multiple fields page.

Advanced parameters

The 'grouping' parameter can be used to aggregate a column.