|
|
| (17 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| == Report Builder API overview ==
| | {{Template:Migrated|newDocId=/docs/apis/core/reportbuilder/}} |
| | |
| == System Reports ==
| |
| | |
| === Introduction ===
| |
| | |
| === Column ===
| |
| | |
| ==== Column overview ====
| |
| | |
| Column instances define the data captured/displayed within a report column - typically:<br />
| |
| | |
| * How the data is retrieved, either a simple SQL table.field fragment or an expression that returns a value
| |
| * They type of data that is being retrieved (int, text, datetime, etc)
| |
| * How that data should be presented in a report (for instance calling userdate() on datetime types)
| |
| | |
| ==== Column types ====
| |
| | |
| * '''Text'''
| |
| * '''Integer''' (Integer numbers)
| |
| * '''Float''' (Decimal numbers)
| |
| * '''Timestamp''' (Dates)
| |
| * '''Boolean''' (Yes / No values)
| |
| * '''Longtext'''
| |
| | |
| ==== Creating columns ====
| |
| | |
| To create a new column, just create a new instance of '''reportbuilder/classes/local/report/column.php''' class with:<br />
| |
| <code php>
| |
| * string $name
| |
| * ?lang_string $title
| |
| * string $entityname
| |
| </code>
| |
| | |
| And use:<br />
| |
| '''add_joins()''' to add any extra SQL joins the column might need<br />
| |
| '''set_type()''' to add the column type (All constant types are defined within the same column class)<br />
| |
| '''set_is_sortable()''' to define if column can be sorted (For example we don't want to sort if the column shows just a picture)<br />
| |
| '''add_callback()''' to format the output of the column<br />
| |
| '''add_field()''' to add any db fields format callback might need<br />
| |
| | |
| Example:
| |
| | |
| <code php>
| |
| $columns[] = (new column(
| |
| 'starttime',
| |
| new lang_string('task_starttime', 'admin'),
| |
| $this->get_entity_name()
| |
| ))
| |
| ->add_joins($this->get_joins())
| |
| ->set_type(column::TYPE_TIMESTAMP)
| |
| ->add_field("{$tablealias}.timestart")
| |
| ->set_is_sortable(true)
| |
| ->add_callback([format::class, 'userdate']);
| |
| </code>
| |
| | |
| === Filter ===
| |
| | |
| ==== Filter overview ====
| |
| | |
| Report filters can be defined for a report and allow users to narrow down (filter) the data that is displayed in a report
| |
| | |
| * They define the data being filtered, either a simple SQL fragment or expression.
| |
| * The type of filtering being performed (int, text, datetime, etc).
| |
| | |
| Filter types are extendable, allowing for the addition of many more as suits each use case. We have provided common ones that cover most use cases.
| |
| | |
| Note that filters & columns are entirely separate concepts in the report, and each can be used without a matching column/filter (that is to say, we can add a report filter for a user field without needing the column for the same field to be present in the report).
| |
| | |
| ==== Filter types ====
| |
| | |
| * '''Text''' (reportbuilder/classes/local/filters/text.php)
| |
| * '''Date''' (reportbuilder/classes/local/filters/date.php)
| |
| * '''Number''' (reportbuilder/classes/local/filters/number.php)
| |
| * '''Boolean Select''' (reportbuilder/classes/local/filters/boolean_select.php)
| |
| * '''Select''' (reportbuilder/classes/local/filters/select.php)
| |
| * '''Course selector''' (reportbuilder/classes/local/filters/course_selector.php)
| |
| | |
| ==== Creating filters ====
| |
| | |
| To create a new filter, just create a new instance of '''reportbuilder/classes/local/report/filter.php''' class with:<br />
| |
| <code php>
| |
| * string $filterclass
| |
| * string $name
| |
| * lang_string $header
| |
| * string $entityname
| |
| * string $fieldsql = ''
| |
| * array $fieldparams = []
| |
| </code>
| |
| | |
| Example:
| |
| | |
| <code php>
| |
| $filters[] = (new filter(
| |
| course_selector::class,
| |
| 'courseselector',
| |
| new lang_string('courses'),
| |
| $this->get_entity_name(),
| |
| "{$tablealias}.id"
| |
| ))
| |
| ->add_joins($this->get_joins());
| |
| </code>
| |
| | |
| === Entity ===
| |
| | |
| An Entity is a collection of elements where an element is a column or a filter. An entity is re-usable across many system reports and we can add only the entity columns or filters that we need on each report.
| |
| | |
| ==== Create an entity ====
| |
| | |
| To create an entity, the new entity class must extend '''/reportbuilder/classes/local/entities/base.php''' class and must include these methods:
| |
| | |
| <code php>
| |
| get_default _table_aliases()
| |
| get_default_entity_title()
| |
| get_default_entity_name()
| |
| initialise()
| |
| get_all_columns()
| |
| get_all_filters()
| |
| </code>
| |
| | |
| ===== get_default _table_aliases() =====
| |
| Defines the SQL alias for the database tables the entity uses.
| |
| | |
| ===== get_default_entity_title() =====
| |
| Defines the default title for this entity.
| |
| | |
| ===== get_default_entity_name() =====
| |
| Defines the default internal name for this entity that will be used to manage columns and filters.
| |
| | |
| ===== initialise() =====
| |
| This is where we '''add''' the entity columns and filters.
| |
| | |
| ===== get_all_columns() and get_all_filters() =====
| |
| This is where we '''define''' the entity columns and filters.
| |
| | |
| ==== Examples ====
| |
| | |
| Report Builder has two entities as an example to start building reports:
| |
| | |
| '''User entity''': reportbuilder/classes/local/entities/user.php<br />
| |
| '''Course entity''': reportbuilder/classes/local/entities/course.php
| |
| | |
| === Actions ===
| |
| | |
| === System reports ===
| |
| | |
| ==== Use an entity ====
| |
