Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Reports

From MoodleDocs
Revision as of 13:04, 14 July 2021 by David Mudrak (talk | contribs) (Text replacement - "<code>" to "<syntaxhighlight lang="php">")

Moodle 2.2


In Moodle 2.2 the Course reports and Admin reports were combined into one Reports directory (/report) that serves both needs.


Overview

A report is a folder of code under /report. For example, you might make a folder in there called myreport.

In there, the only code you are required to have is an index.php file. This will normally display a simple HTML form for controlling the report, and, the code for displaying the report. You will probably also want a language file, which would be called lang/en/report_myreport.php following the example above.

In addition, you can add any other PHP code you like, and then link people to it from index.php.

So, the minimal code layout is:

report/
 backups/
 completion/
 ...
 myreport/
  lang/
   en/
    report_myreport.php
  index.php
  version.php
...

What to do in index.php

The simplest way to work this out is by example. You should look at some of the reports that ship with Moodle. report/log is a good one to start with. Let us go through that example to see what is there (I will put into italics the bits that are more advanced):

  1. Require some libraries.
  2. Check the user is logged in and has appropriate permissions - all external admin pages use admin_externalpage_setup() which by default requires 'moodle/site:config' capability
  3. Get the parameters from the URL that control the report, and clean them up a bit.
  4. Print the page header. Since this is an administration page, we need to do this using the admin_externalpage... functions.
  5. Display a table with data and paging controls
  6. Print the footer

How your report gets included in the navigation

Reports can present itself in different contexts:

  • system level - controlled by settings.php
  • at user level - controlled by *_extend_navigation_user() callbacks
  • at course level - controlled by *_extend_navigation_course() callbacks
  • at module level - controlled by *_extend_navigation_module() callbacks

In our example the configlog report is usable only at the system level, the admin tree integration is done through settings.php file $ADMIN->add('reports', new admin_externalpage('reportconfiglog', get_string('configlog', 'report_configlog'), "$CFG->wwwroot/report/configlog/index.php")); $settings = null; The <syntaxhighlight lang="php">$settings = null tells moodle that plugin does not have any settings and only want to display link to external admin page.

If you want to include your report in course navigation for example you need to create lib.php file and add following function:

function report_myreport_extend_navigation_course($navigation, $course, $context) {

   if (has_capability('report/myreport:view', $context)) {
       $url = new moodle_url('/report/myreport/index.php', array('id'=>$course->id));
       $navigation->add(get_string('pluginname', 'report_myreport'), $url, navigation_node::TYPE_SETTING, null, null, new pix_icon('i/report', ));
   }

}

You will also need access.php file with definition of 'report/myreport:view' capability.

Callbacks

This section includes the callbacks that a report should define. callbacks are normally defined in lib.php of the report.

report_myreport_supports_logstore

Moodle 2.7


You need to define this callback only if your report uses logstores to fetch information. This function takes a store instance as an argument and returns boolean true/false depending on if your report supports this store or not. This callback is used in various managment interfaces to let admins know the dependencies of your report on logstores.

See Migrating log access in reports for further details on how to use logstores in reports. Example:- <syntaxhighlight lang="php">/**

* Callback to verify if the given instance of store is supported by this report or not.
*
* @param string $instance store instance.
*
* @return bool returns true if the store is supported by the report, false otherwise.
*/

function report_myreport_supports_logstore($instance) {

   // Use '\core\log\sql_select_reader' instead of '\core\log\sql_reader' in Moodle 2.7 and Moodle 2.8.
   if ($instance instanceof \core\log\sql_reader) {
       return true;
   }
   return false;

}

Strings you must define in you lang/en/report_myreport.php

You just need to define

$string['pluginname'] = 'What my report is called';

to make the report show up properly in the admin tree, but if your report does anything interesting, you will almost certainly need more.

See also