Report builder API: Difference between revisions
No edit summary |
|||
Line 6: | Line 6: | ||
=== Column === | === 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 ==== | ==== Column types ==== | ||
* '''Text''' | |||
* '''Integer''' (Integer numbers) | |||
* '''Float''' (Decimal numbers) | |||
* '''Timestamp''' (Dates) | |||
* '''Boolean''' (Yes / No values) | |||
* '''Longtext''' | |||
==== Creating columns ==== | ==== 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 === | ||
==== 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 ==== | ==== Filter types ==== |
Revision as of 14:21, 30 April 2021
Report Builder API overview
System Reports
Introduction
Column
Column overview
Column instances define the data captured/displayed within a report column - typically:
- 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:
- string $name
- ?lang_string $title
- string $entityname
And use:
add_joins() to add any extra SQL joins the column might need
set_type() to add the column type (All constant types are defined within the same column class)
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)
add_callback() to format the output of the column
add_field() to add any db fields format callback might need
Example:
$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']);
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:
- string $filterclass
- string $name
- lang_string $header
- string $entityname
- string $fieldsql =
- array $fieldparams = []
Example:
$filters[] = (new filter(
course_selector::class,
'courseselector',
new lang_string('courses'),
$this->get_entity_name(),
"{$tablealias}.id"
))
->add_joins($this->get_joins());
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:
get_default _table_aliases()
get_default_entity_title()
get_default_entity_name()
initialise()
get_all_columns()
get_all_filters()
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
Course entity: reportbuilder/classes/local/entities/course.php