Hello World Source

The code below is one of the simplest report sources you could make:

<?php

class rb_source_example1 extends rb_base_source {
    public $base, $joinlist, $columnoptions, $filteroptions;

    function __construct() {
        $this->base = '{course}';
        $this->joinlist = array();
        $this->columnoptions = array(
            new rb_column_option(
                'course',
                'fullname',
                'Course Fullname',
                'base.fullname'
            )
        );
        $this->filteroptions = array();
        $this->sourcetitle   = "Example1";

        parent::__construct();
    }
}
?>

Creating the report

To create this source save the code above in a file called rb_source_example1.php in the /local/reportbuilder/rb_sources/ directory. The class name must start with 'rb_source_', and the class name and filename must match. You should now be able to generate a report based on this source as follows:

1. As a Site Administrator, click on Site administration > Reports > Report builder > Manage reports.
2. Scroll down to New report.
3. Give your report a name e.g. 'Example 1'.
4. Choose the 'Example1' source from the pulldown menu.
5. Click Save changes.

You will be taken to the settings page for the new report, which is where a Site Administrator can configure the report to appear the way they want. While the source describes what columns can be included in the report, it is up to the administrator to decide which columns are shown. Since we've only described one column so far, let's just add that one and see what the report looks like:

1. From the settings page for your report, click on the Columns tab.
2. In the Report columns section choose the Course Fullname column from the Add another column... pulldown menu.
3. Click Save changes.

You should now be able to see the report by clicking View this report.

Understanding the report

This should give a list of all the courses in your site, including the top-level 'front page' course. If you don't have any courses in your site yet you may want to create a few for test purposes.

Here's a breakdown of what this does:

class rb_source_example1 extends rb_base_source {

Defines a report builder source, which extends the base source. This gives the source access to a whole set of useful generic report builder methods.

    public $base, $joinlist, $columnoptions, $filteroptions;

Defines four class properties. These are the minimum properties needed to write a source, there are a number of additional, optional properties.

    function __construct() {

The constructor function is called when a new source is created. It initializes all the properties needed by the source (see below).

        global $CFG;
        $this->base = $CFG->prefix . 'course';

Defines the source's "base" table. This is the name of a report builder table that the source is based on. Your choice will determine the contents of the report. In this case, because we are creating a report on courses, the course table is the most obvious choice for base table. It is also possible to use a sub-query as a base table although you need to make sure the sub-query defines a unique field called 'id' as this is used as the default field for sorting.

       $this->joinlist = array();

The joinlist property contains an array of join objects, each of which defines a connection between your base table and another database table. Without joins, the only database fields that would be available would be those in the base table. Because this is a very basic source there are no joins yet.

        $this->columnoptions = array(
            new rb_column_option(
                'course',
                'fullname',
                'Course Fullname',
                'base.fullname'
            )
        );

The columnoptions property contains an array of column option objects. Each column option object defines a column that can be included in a report that uses this source. It is up to the person building the report to decide which columns they actually want to use. See adding a column for more information about this section.

        $this->filteroptions = array();

The filteroptions property contains an array of filter option objects, which define possible search options for the report. Because this is a very basic source there are no search options yet, although some will be added later.

        parent::__construct();

At the end of the constructor, we call the constructor of the base source. This contains a number of checks to validate the source and warn the developer if any required fields have been forgotten or invalid joins created.