Admin reports

Moodle 2.1

This document applies to Moodle versions before 2.2. See Reports for the new unified reports in Moodle 2.2 and later.

Overview

An admin report is a folder of code under admin/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 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:

admin/
  ...
  report/
    backups/
    capability/
    ...
    myreport/
      lang/
        en_utf8/
          report_myreport.php
      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. admin/report/capability (warning: capability report does not exist in v2.4+), 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.):

1. Require some libraries. Admin reports will always need config.php and adminlib.php.
2. 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.)
3. Get the parameters from the URL that control the report, and clean them up a bit.
4. Include some JavaScript code that enhances the report for people with JavaScript turned on in their browser.
5. Log this request.
6. 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.
7. Display a form to control the report.
8. 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.)
9. Print the footer, using the admin_externalpage... function.
10. 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

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 "reportmyreport".

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:

 <?php  // $Id$
 $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.)

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

You just need to define

 $string["myreport"] = '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.

Creating a new report in admin block

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:

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

• System images report this is another very simple report, in contrib. Might be a good one to look at.