Note:

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

Reports: Difference between revisions

From MoodleDocs
m (Text replacement - "</code>" to "</syntaxhighlight>")
 
(20 intermediate revisions by 6 users not shown)
Line 2: Line 2:


In Moodle 2.2 the [[Course reports]] and [[Admin reports]] were combined into one Reports directory (/report) that serves both needs.
In Moodle 2.2 the [[Course reports]] and [[Admin reports]] were combined into one Reports directory (/report) that serves both needs.
TODO: finish updating this document.




Line 11: Line 8:
A report is a folder of code under /report. For example, you might make a folder in there called '''myreport'''.
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_utf8/report_myreport.php following the example above.  
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.
In addition, you can add any other PHP code you like, and then link people to it from index.php.
Line 17: Line 14:
So, the minimal code layout is:
So, the minimal code layout is:


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


==What to do in index.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. [http://cvs.moodle.org/moodle/admin/report/capability/index.php?view=markup admin/report/capability], 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 - the things that the capability report does, but which a simple report will not need to do.):
The simplest way to work this out is by example. You should look at some of the reports that ship with Moodle. [https://github.com/moodle/moodle/blob/master/report/configlog/index.php 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):
# Require some libraries. Admin reports will always need config.php and adminlib.php.
 
# Check the user is logged in and has appropriate permissions. ''(Normally admin reports are controlled by the 'moodle/site:viewreports' capability, the capability report is a special case.)''
# Require some libraries.
# 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
# Get the parameters from the URL that control the report, and clean them up a bit.
# Get the parameters from the URL that control the report, and clean them up a bit.
# ''Include some JavaScript code that enhances the report for people with JavaScript turned on in their browser.''
# Print the page header. Since this is an administration page, we need to do this using the admin_externalpage... functions.  
# Log this request.
# Display a table with data and paging controls
# Print the page header. Since this is an administration page, we need to do this using the admin_externalpage... functions. You probably just need to copy these two lines exactly, then replace 'capability' with your report name.
# Print the footer
# Display a form to control the report.
# If the URL contains all the parameters needed to generate the report, do so, and display the results. ''(You don't need to understand the details of what the capability report is doing, because your report will do something different. However, the general structure will probably be the same: get some data out of the database, then display it.)''
# Print the footer, using the admin_externalpage... function.
# ''Define some functions, if that is the best way to structure the code of your report. You could, of course, create a separate lib.php file inside your report folder.''


==How your report gets included in the admin tree==
==How your report gets included in the navigation ==


By default, your report will be included in the admin tree under the 'Reports' section, and it will only appear to people with the 'moodle/site:viewreports' capability. If the report is in the ''myreport'' folder, then the report name will be get_string("myreport", "report_''myreport''"). The report name, needed for the call to admin_externalpage_setup, will be "report''myreport''".
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


If you want more control over how your report appears, for example, if you want it to appear somewhere other than under Reports, or if you want it to be controlled by another capability, then you can create a settings.php file. For example, for the capability report, there is a settings.php file that contains:
In our example the configlog report is usable only at the system level, the admin tree integration is done through settings.php file
<syntaxhighlight lang="php">
$ADMIN->add('reports', new admin_externalpage('reportconfiglog', get_string('configlog', 'report_configlog'), "$CFG->wwwroot/report/configlog/index.php"));
$settings = null;
</syntaxhighlight>
The <syntaxhighlight lang="php">$settings = null</syntaxhighlight> tells moodle that plugin does not have any settings and only want to display link to external admin page.


<?php  // $Id$
If you want to include your report in course navigation for example you need to create lib.php file and add following function:
$ADMIN->add('''"roles"''', new admin_externalpage('reportcapability', get_string('capability', 'report_capability'), "$CFG->wwwroot/$CFG->admin/report/capability/index.php",'''"moodle/role:manage"'''));
?>


(The two non-standard bits there have been put into bold.)
<syntaxhighlight lang="php">
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', ''));
    }
}
</syntaxhighlight>


==Strings you must define in you lang/en_utf8/report_''myreport''.php==
You will also need access.php file with definition of  'report/myreport:view' capability.


You just need to define
== Callbacks ==
This section includes the callbacks that a report should define. callbacks are normally defined in lib.php of the report.


$string["''myreport''"] = 'What my report is called';
=== report_myreport_supports_logstore ===
{{Moodle 2.7}}


to make the report show up properly in the admin tree, but if your report does anything interesting, you will almost certainly need more.
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;
}
</syntaxhighlight>


== Creating a new report in admin block ==
==Strings you must define in you lang/en/report_''myreport''.php==


You just need to define
<syntaxhighlight lang="php">
$string['pluginname'] = 'What my report is called';
</syntaxhighlight>


I am using Moodle 1.9. I have created a new reporting module in my local moodle server.  I tried following the examples on this page but was not able to get the new report folder to show in my menu, the admin_externalpage functions where failing. To accomplish the same thing, I completed these steps:
to make the report show up properly in the admin tree, but if your report does anything interesting, you will almost certainly need more.
 
'''1 -''' Created a new folder under admin\report, called AU_ProfessionalDevelopment
 
'''2 -''' Copied index.php and settings.php from the admin\report\question folder into the AU_ProfessionalDevelopment folder.
 
'''3 -''' edited setting.php, updating the string '''question''' with folder name '''AU_ProfessionalDevelopment'''.
 
'''4 -''' edited index.php, stripping out most of the code, leaving the following:
 
    require_once('../../../config.php');
    require_once($CFG->libdir.'/adminlib.php');
    admin_externalpage_setup('reportAU_ProfessionalDevelopment');
    admin_externalpage_print_header();
    admin_externalpage_print_footer();
 
'''5''' Reloaded the moodle page (i am logged in as the admin - and can see the Admin. Block). I can see '''AU_ProfessionalDevelopment''' in the admin\report block.  Clicking on it loads my page with the admin header and footer.


==See also==
==See also==

Latest revision as of 20:15, 14 July 2021

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

$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:-

/**
 * 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