Gradebook export

Introduction

This document is for developers wanting to allow users to export Moodle grade information in a new export format. Here is another document if you are looking for an introduction to exporting grades from Moodle

Moodle allows authorised users to export grade information. This can be used to to provide a teacher with a copy of their gradebook at a particular point in time or to extract student assessment data from Moodle so that it can be loaded into a piece of software other than Moodle.

Since 1.9 the Moodle gradebook has provided support for the addition of plug-in export modules to allow Moodle to export grade information in new or custom formats. Moodle includes several default gradebook export modules that produce formats like Excel or CSV that will work in most situations.

This document describes how to implement a custom gradebook export plug-in in case you need gradebook data in a format that is not available using the provided export modules.

Getting started

The gradebook export modules are located in the grade/export directory. To create a new gradebook export, complete the steps listed below.

Note: For the remainder of this topic when you see [newexport], replace it with the short name you have choosen for your export, do not include the []. Moodle comes with the following exports: ods, txt, xls, and xml so you cannot use those names.

New Gradebook Export Creation Steps

• Decide on a short name for this new export. This name will be referred to as [newexport] the remainder of this topic.
• Create a new directory in Moodle's grade/export directory for your files.
• Review the export formats that ship with Moodle and choose the export format most like the one you wish to develop. Refer to that export's files as needed.
• Copy the files from the export format you selected into your newly created directory of grade/export/[newexport]
• Alter each of the files listed below so they produce the data you desire.
• Click on Notifications in the Site Administration menu to go through the upgrade process and set up the permissions for your export format.
• Test, test, test - until your export performs properly.

/grade/export/[newexport]/db/access.php

The access.php file makes your gradebook export available to teachers and allows the security administrator to decide who can and cannot access this export module. See the "View role details" page in Site Administration > Users > Permissions > Define roles for more details.

For your export to have the same set of permissions as the other exports, change the lines listed below replacing the old export format name with [newexport].

        'gradeexport/[newexport]:view' => array(

        'gradeexport/[newexport]:publish' => array(

The new security role entries will be available after an upgrade has been completed (click the Notifications link in Site Administration). This should not be done until you have worked through each of the files listed in this section.

Note: The gradeexport_[newexport].php file in the lang directory works with the :view and :publish settings to provide a description. See the information about that file for more details.

/grade/export/[newexport]/dump.php

The only change needed in this file is the following capability check:

  require_capability('gradeexport/[newexport]:publish', $context);

/grade/export/[newexport]/export.php

The following lines need to be changed to reflect your new export's name.

  require_once 'grade_export_[newexport].php';

  require_capability('gradeexport/[newexport]:view', $context);

  $export = new grade_export_[newexport]($course, $groupid, $itemids, $export_feedback, $updatedgradesonly, $displaytype, $decimalpoints, $separator);

/grade/export/[newexport]/grade_export_[newexport].php

The following lines need to be changed to reflect your new export's name.

  class grade_export_[newexport] extends grade_export {

  var $plugin = '[newexport]';

  function grade_export_[newexport]($course, $groupid=0, $itemlist=, ...

/grade/export/[newexport]/index.php

The following lines need to be changed to reflect your new export's name.

  require_once 'grade_export_[newexport].php';

  require_capability('gradeexport/[newexport]:view', $context);

  print_grade_page_head($COURSE->id, 'export', '[newexport]', get_string('exportto', 'grades') . ' ' . get_string('modulename', 'gradeexport_[newexport]'));

  $CFG->gradepublishing = has_capability('gradeexport/[newexport]:publish', $context);

  $export = new grade_export_[newexport]($course, $currentgroup, , false, false, $data->display, $data->decimals);

/grade/export/[newexport]/version.php

Use the current dates for your export module. If any adjustments are made to your security or if any database changes are needed (see the db/access.php file above) the version will need to be incremented and an upgrade will be performed (loggin in as admin clicking the Notifications link on the Site Administration causes Moodle to check if an upgrade is necessary).

Your version.php will look something like this ...

    $plugin->version  = 2007092700;
    $plugin->requires = 2007101000;

/lang/en_utf8/gradeexport_[newexport].php

Note: Replace en_utf8 with your language directory if using multiple languages or a language other than English. Copy one of the existing files (i.e. gradeexport_txt.php) to create your new gradebook export language file.

When you first create your gradebook export directory and look in the Action menu of the Moodle gradebook, your new export module will be listed as [[modulename]]. The modulename string in this file will provide the Action menu with the name specified.

The :view and the :publish strings are used to display a meaningful description on the security roles for users. These two descriptions work in conjunction with the db/access.php file. See the information about the db/access.php file for more details.

The gradeexport_txt.php (Plain text file export) is shown below without the PHP tags. Change "Plain text file" to the name of the new export and replace "txt" with the [newexport] value. Change the comments after the ":view" and ":publish" to descriptions that should appear on the role details page for your new export.

    $string['modulename'] = 'Plain text file';
    $string['txt:view'] = 'Use text grade export';
    $string['txt:publish'] = 'Publish TXT grade export';

To better illustrate, if your module had a short name of "sis" and a description of "My Student Info System", then this file would like something like the following ...

    $string['modulename'] = 'My Student Info System';
    $string['sis:view'] = 'Use My SIS grade export';
    $string['sis:publish'] = 'Publish SIS grade export';

Final Checks

To make sure no references to the original export format have been missed you can use grep (in Linux) or an equivalent command in Windows or Mac. For example, if you copied "txt" when creating your export module you could use a command similar to the following.

    grep -R "txt" ./grade/export/[newexport]/

Customizing Your Export

At this point your export is in its own directory, has its own security identifiers, and has its own name but it behaves just like the export you copied from. In this section we will look at how to customize the behavior of your export.

Changing the Grade Export Form Options

The grade export form (used to select options when exporting) can be altered by opening the grade/export/[newexport]/index.php file and finding the line similar to the one shown below:

  $mform = new grade_export_form(null, array('includeseparator'=>true, 'publishing' => true));

The part of that statement starting with array( can be altered to pass feature parameters into the grade_export_form class. Refer to the file grade/export/grade_export_form.php for the details of the available feature parameters and how they affect the grade export form. The grade_export_form.php file should not be altered as it is part of the Moodle core code and will affect the other exports as well.

Changing the Format and Fields in the Export File

To change the format of the export file and the fields in the export file, edit the grade/export/[newexport]/grade_export_[newexport].php file. The echo statements in the print_grades() function determine what will be included in the export file. Make whatever adjustments to the echo statements in this function that your new export needs.

The Grades documentation referenced in the See Also section below will help in understanding the gradebook and what values are available for use in your export. The variables can also be dumped to see their structure and contents.

For example, the following two statements will show you what is in the $userdata->grades and $this->columns structures. If you include these statements in the print_grades() function then you will see the results in your export file.

  var_dump($userdata->grades);
  var_dump($this->columns);

See also

• Grades