Report builder API - Revision history

Devdocsbot: Protected "Report builder API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

2023-05-23T16:01:34Z

Protected "Report builder API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

← Older revision	Revision as of 16:01, 23 May 2023
(No difference)

Devdocsbot: Update migration status and path

2023-05-23T15:59:16Z

Update migration status and path

Show changes

Davidmatamoros: /* Actions */

2021-10-07T13:44:19Z

Actions

← Older revision		Revision as of 13:44, 7 October 2021
Line 103:		Line 103:
	'''Course entity''': [https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/entities/course.php reportbuilder/classes/local/entities/course.php]		'''Course entity''': [https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/entities/course.php reportbuilder/classes/local/entities/course.php]
	=== Actions ===		=== Actions ===
	Report actions can be defined in system reports to provide CTA links for each row in the report. Using :placeholder elements in the action URLs allows them to be specific to the row content - e.g. to always provide a link to the current user/course of the current row		[[File:Actions.jpg\|alt=Example of actions on the tasks logs system report\|thumb\|Example of actions on the tasks logs system report]]
	<syntaxhighlight lang="php">		Report actions can be defined in system reports to provide CTA links for each row in the report. Using :placeholder elements in the action URLs allows them to be specific to the row content - e.g. to always provide a link to the current user/course of the current row<syntaxhighlight lang="php">
	$this->add_action((new action(		$this->add_action((new action(
	new moodle_url('/admin/tasklogs.php', ['logid' => ':id']),		new moodle_url('/admin/tasklogs.php', ['logid' => ':id']),

Davidmatamoros: /* Filter types */

2021-10-07T13:29:02Z

Filter types

← Older revision		Revision as of 13:29, 7 October 2021
Line 51:		Line 51:
	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).		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 ====
	* '''Text''' (reportbuilder/classes/local/filters/text.php)		* '''Text''' ([https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/filters/text.php reportbuilder/classes/local/filters/text.php])
	* '''Date''' (reportbuilder/classes/local/filters/date.php)		* '''Date''' ([https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/filters/date.php reportbuilder/classes/local/filters/date.php])
	* '''Number''' (reportbuilder/classes/local/filters/number.php)		* '''Number''' ([https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/filters/number.php reportbuilder/classes/local/filters/number.php])
	* '''Boolean Select''' (reportbuilder/classes/local/filters/boolean_select.php)		* '''Boolean Select''' ([https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/filters/boolean_select.php reportbuilder/classes/local/filters/boolean_select.php])
	* '''Select''' (reportbuilder/classes/local/filters/select.php)		* '''Select''' ([https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/filters/select.php reportbuilder/classes/local/filters/select.php])
	* '''Course selector''' (reportbuilder/classes/local/filters/course_selector.php)		* '''Course selector''' ([https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/filters/course_selector.php reportbuilder/classes/local/filters/course_selector.php])
			* '''Duration''' ([https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/filters/duration.php reportbuilder/classes/local/filters/duration.php])
	==== Creating filters ====		==== Creating filters ====
	To create a new filter, just create a new instance of '''[https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/report/filter.php reportbuilder/classes/local/report/filter.php]''' class with:<br />		To create a new filter, just create a new instance of '''[https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/report/filter.php reportbuilder/classes/local/report/filter.php]''' class with:<br />

Davidmatamoros at 12:26, 7 October 2021

2021-10-07T12:26:29Z

← Older revision		Revision as of 12:26, 7 October 2021
Line 132:		Line 132:
	$this->add_entity($entitymain);		$this->add_entity($entitymain);
	</syntaxhighlight>		</syntaxhighlight>
	After that, if the report will have 'Actions', it needs to define the columns it will use:		After that, if the report will have 'Actions', it needs to define the columns these actions will use:
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	$this->add_base_fields("{$entitymainalias}.id");		$this->add_base_fields("{$entitymainalias}.id");
Line 144:		Line 144:
	));		));
	</syntaxhighlight>		</syntaxhighlight>
	Once all entities have been added it needs to define which columns it needs to show in the order we need:		Once all entities have been added it needs to define which columns it needs to show '''in the order we need''':
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	$columns = [		$columns = [
Line 173:		Line 173:
	)));		)));
	</syntaxhighlight>		</syntaxhighlight>
			'''Note''' that the placeholders used here (:id in this example) have been previously added using '''add_base_fields'''();

	Once the whole report has been defined, is possible to set if the report will be downloadable or not:		Once the whole report has been defined, is possible to set if the report will be downloadable or not:
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">

Davidmatamoros at 12:18, 7 October 2021

2021-10-07T12:18:24Z

← Older revision		Revision as of 12:18, 7 October 2021
Line 190:		Line 190:
	$this->set_initial_sort_column('task_log:starttime', SORT_DESC);		$this->set_initial_sort_column('task_log:starttime', SORT_DESC);
	</syntaxhighlight>		</syntaxhighlight>
			==== Examples ====
			Moodle has two system reports as an example:

			'''Task logs''': [https://github.com/moodle/moodle/blob/master/admin/classes/local/systemreports/task_logs.php admin/classes/local/systemreports/task_logs.php]<br />
			'''Config changes''': [https://github.com/moodle/moodle/blob/master/report/configlog/classes/local/systemreports/config_changes.php report/configlog/classes/local/systemreports/config_changes.php]

Davidmatamoros: /* Creating columns */

2021-10-07T12:07:03Z

Creating columns

← Older revision		Revision as of 12:07, 7 October 2021
Line 17:		Line 17:
	* '''Longtext'''		* '''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 />		To create a new column, just create a new instance of '''[https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/report/column.php reportbuilder/classes/local/report/column.php]''' class with:<br />
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	* string $name		* string $name
Line 58:		Line 58:
	* '''Course selector''' (reportbuilder/classes/local/filters/course_selector.php)		* '''Course selector''' (reportbuilder/classes/local/filters/course_selector.php)
	==== Creating filters ====		==== Creating filters ====
	To create a new filter, just create a new instance of '''reportbuilder/classes/local/report/filter.php''' class with:<br />		To create a new filter, just create a new instance of '''[https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/report/filter.php reportbuilder/classes/local/report/filter.php]''' class with:<br />
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	* string $filterclass		* string $filterclass
Line 84:		Line 84:
	All report elements can be defined within the reports themselves - but entities mean it's much easier to create re-usable components, and will also help in the long term with custom reports		All report elements can be defined within the reports themselves - but entities mean it's much easier to create re-usable components, and will also help in the long term with custom reports
	==== Create an entity ====		==== 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:		To create an entity, the new entity class must extend '''[https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/entities/base.php reportbuilder/classes/local/entities/base.php]''' class and must include these methods:
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	get_default_table_aliases()		get_default_table_aliases()
Line 114:		Line 114:
	System reports are a consistent way of providing reporting data, with paging, filtering, exporting standardized across them. Once the groundwork is done in defining the report elements in entities, it's possible to implement them with minimal code just by adding entities to the report, and defining which elements you want to use from them		System reports are a consistent way of providing reporting data, with paging, filtering, exporting standardized across them. Once the groundwork is done in defining the report elements in entities, it's possible to implement them with minimal code just by adding entities to the report, and defining which elements you want to use from them
	==== Create a new system report using entities ====		==== Create a new system report using entities ====
	To create a new system report just create a new class extending '''reportbuilder/classes/system_report.php'''.		To create a new system report just create a new class extending '''[https://github.com/moodle/moodle/blob/master/reportbuilder/classes/system_report.php reportbuilder/classes/system_report.php]'''.

	The first method that we need is '''initialise()''':		The first method that we need is '''initialise()''':

Davidmatamoros: /* Examples */

2021-10-07T11:56:58Z

Examples

← Older revision		Revision as of 11:56, 7 October 2021
Line 56:		Line 56:
	* '''Boolean Select''' (reportbuilder/classes/local/filters/boolean_select.php)		* '''Boolean Select''' (reportbuilder/classes/local/filters/boolean_select.php)
	* '''Select''' (reportbuilder/classes/local/filters/select.php)		* '''Select''' (reportbuilder/classes/local/filters/select.php)
	* '''Course selector''' (reportbuilder/classes/local/filters/course_selector.php)		* '''Course selector''' (reportbuilder/classes/local/filters/course_selector.php)
	==== Creating filters ====		==== Creating filters ====
	To create a new filter, just create a new instance of '''reportbuilder/classes/local/report/filter.php''' class with:<br />		To create a new filter, just create a new instance of '''reportbuilder/classes/local/report/filter.php''' class with:<br />
Line 99:		Line 99:
	Report Builder has two entities as an example to start building reports:		Report Builder has two entities as an example to start building reports:

	'''User entity''': reportbuilder/classes/local/entities/user.php<br />		'''User entity''': [https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/entities/user.php reportbuilder/classes/local/entities/user.php]<br />
	'''Course entity''': reportbuilder/classes/local/entities/course.php		'''Course entity''': [https://github.com/moodle/moodle/blob/master/reportbuilder/classes/local/entities/course.php reportbuilder/classes/local/entities/course.php]
	=== Actions ===		=== Actions ===
	Report actions can be defined in system reports to provide CTA links for each row in the report. Using :placeholder elements in the action URLs allows them to be specific to the row content - e.g. to always provide a link to the current user/course of the current row		Report actions can be defined in system reports to provide CTA links for each row in the report. Using :placeholder elements in the action URLs allows them to be specific to the row content - e.g. to always provide a link to the current user/course of the current row

Pholden: /* Create an entity */

2021-07-28T09:40:19Z

Create an entity

Show changes

Mudrd8mz: Text replacement - "" to ""

2021-07-14T20:23:57Z

Text replacement - "</code>" to "</syntaxhighlight>"

← Older revision		Revision as of 20:23, 14 July 2021
Line 33:		Line 33:
	* ?lang_string $title		* ?lang_string $title
	* string $entityname		* string $entityname
	</~~code~~>		</syntaxhighlight>

	And use:<br />		And use:<br />
Line 55:		Line 55:
	->set_is_sortable(true)		->set_is_sortable(true)
	->add_callback([format::class, 'userdate']);		->add_callback([format::class, 'userdate']);
	</~~code~~>		</syntaxhighlight>

	=== Filter ===		=== Filter ===
Line 89:		Line 89:
	* string $fieldsql = ''		* string $fieldsql = ''
	* array $fieldparams = []		* array $fieldparams = []
	</~~code~~>		</syntaxhighlight>

	Example:		Example:
Line 102:		Line 102:
	))		))
	->add_joins($this->get_joins());		->add_joins($this->get_joins());
	</~~code~~>		</syntaxhighlight>

	=== Entity ===		=== Entity ===
Line 123:		Line 123:
	get_all_columns()		get_all_columns()
	get_all_filters()		get_all_filters()
	</~~code~~>		</syntaxhighlight>

	===== get_default _table_aliases() =====		===== get_default _table_aliases() =====
Line 158:		Line 158:
	true,		true,
	)));		)));
	</~~code~~>		</syntaxhighlight>

	=== System reports ===		=== System reports ===
Line 174:		Line 174:
	*/		*/
	protected function initialise(): void {		protected function initialise(): void {
	</~~code~~>		</syntaxhighlight>

	The initialise method needs to get the main entity, set the main table it needs to use and add the entity to the report:		The initialise method needs to get the main entity, set the main table it needs to use and add the entity to the report:
Line 185:		Line 185:
	$this->set_main_table('task_log', $entitymainalias);		$this->set_main_table('task_log', $entitymainalias);
	$this->add_entity($entitymain);		$this->add_entity($entitymain);
	</~~code~~>		</syntaxhighlight>

	After that, if the report will have 'Actions', it needs to define the columns it will use:		After that, if the report will have 'Actions', it needs to define the columns it will use:
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	$this->add_base_fields("{$entitymainalias}.id");		$this->add_base_fields("{$entitymainalias}.id");
	</~~code~~>		</syntaxhighlight>

	Now, after adding our first entity, the report can use the columns and filters from it OR more entities can be added to the report using SQL joins:		Now, after adding our first entity, the report can use the columns and filters from it OR more entities can be added to the report using SQL joins:
Line 199:		Line 199:
	"LEFT JOIN {user} {$entituseralias} ON {$entituseralias}.id = {$entitymainalias}.userid"		"LEFT JOIN {user} {$entituseralias} ON {$entituseralias}.id = {$entitymainalias}.userid"
	));		));
	</~~code~~>		</syntaxhighlight>

	Once all entities have been added it needs to define which columns it needs to show in the order we need:		Once all entities have been added it needs to define which columns it needs to show in the order we need:
Line 211:		Line 211:

	$this->add_columns_from_entities($columns);		$this->add_columns_from_entities($columns);
	</~~code~~>		</syntaxhighlight>

	After defining the columns, it needs to define all the filters (or empty array for no filters) that it will use:		After defining the columns, it needs to define all the filters (or empty array for no filters) that it will use:
Line 222:		Line 222:

	$this->add_filters_from_entities($filters);		$this->add_filters_from_entities($filters);
	</~~code~~>		</syntaxhighlight>

	In case it needs actions for each report row, they can be defined like:		In case it needs actions for each report row, they can be defined like:
Line 232:		Line 232:
	new pix_icon('t/download', get_string('download')),		new pix_icon('t/download', get_string('download')),
	)));		)));
	</~~code~~>		</syntaxhighlight>

	Once the whole report has been defined, is possible to set if the report will be downloadable or not:		Once the whole report has been defined, is possible to set if the report will be downloadable or not:
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	$this->set_downloadable(true);		$this->set_downloadable(true);
	</~~code~~>		</syntaxhighlight>

	==== Use an entity ====		==== Use an entity ====
Line 248:		Line 248:
	$column->set_title(new lang_string('user', 'admin'));		$column->set_title(new lang_string('user', 'admin'));
	}		}
	</~~code~~>		</syntaxhighlight>

	==== Set a default initial sort direction ====		==== Set a default initial sort direction ====
Line 256:		Line 256:
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	$this->set_initial_sort_column('task_log:starttime', SORT_DESC);		$this->set_initial_sort_column('task_log:starttime', SORT_DESC);
	</~~code~~>		</syntaxhighlight>