General report plugins

Jump to: navigation, search
General report plugins
Project state Implemented
Tracker issue MDL-29030
Discussion n/a
Assignee Petr Škoda (škoďák)

Moodle 2.2


General reports are a new plugin type introduced in Moodle 2.2. They replace all previous report types with the exception of gradebook reports. Plugins can be implemented to work in different contexts, they are accessible only via navigation menu (links are added there via plugin callbacks). System reports may also add links to settings tree menu via the settings.php file.

Previous problems

Before 2.2 we had course reports, admin reports and hardcoded user reports:

  • only two contexts fully supported (system and course)
  • hardcoded user reports
  • nonstandard admin reports
  • missing admin management of reports (enable, disable, uninstall, etc.)
  • non-report plugins included in admin reports (customlang, splamcleaner)

Benefits

  • standardised /report/ plugin type is good starting place for development of new reports that we need really badly
  • reports can be context oriented - we need custom reports at all levels, especially user contexts
  • cleanup in /admin/
  • it is possible to remove or replace official reports (no hardcoded links)
  • pluggable reports will significantly help when rewriting logging subsystem in 2.3

Upgrades

How to migrate existing admin reports:

  1. move all files to new /report/yourplugin/ location
  2. if settings.php exists add $settings=null;
  3. if settings.php does not exist create it and link the report, index.php is not linked automatically any more
  4. update require('../../../config.php'); - remove one ../
  5. update all others includes and requires
  6. update all links to report pages by removing /admin/ or /$CFG->admin/
  7. rename/add language pack file with at least 'pluginname' string
  8. update CSS selectors
  9. if your report has a cron function defined in a file called cron.php, you need to move it into lib.php.


How to migrate existing course reports (optional for now, but recommended):

  1. move all files to new /report/yourplugin/ location
  2. update require('../../config.php'); - remove one ../
  3. update all others includes and requires
  4. update all links to report pages by removing /course/ part
  5. rename language pack file
  6. update all language strings (use 'report_yourplugin' instead of 'coursereport_yourplugin') - use AMOS hints in commit message
  7. update all capability names
  8. grep the plugin codebase and look for any remaining 'coursereport' occurrences
  9. add new navigation hooks in lib.php - ex: report_stats_extend_navigation_course(), report_stats_extend_navigation_user()
  10. add new page types in lib.php
  11. create db/install.php migration script - delete old settings and capabilities (see converted plugins for examples), migrate db tables if present (see resource modules or workshop for examples)
  12. update CSS selectors

FAQs

Are gradebook reports affected?
No. Gradebook reports are more specialised, they span multiple contexts and read information directly from gradebook.
Is it necessary to migrate existing admin reports?
Yes. Old admin reports directory is completely ignored.
Is it difficult to migrate admin reports?
No, it usually takes less than an hour to migrate and test one old admin report.
Is it necessary to migrate all course reports for 2.2
No. The course reports were deprecated in 2.2, but the support for them will be removed later in 2.3.
What is the difference between report and admin tool?
Report is a view of live or historical data, it may also contain export feature, reports usually do not modify data. Admin tools are intended mostly for administrators, they usually work only in system context.
Is it possible to create course category report?
Not yet, the course category navigation is not fully implemented yet.
Did you fix/improve plugin XYZ at the same time?
No. Because we need to improve logging subsystem first.

See also