Note:

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

Gradebook import: Difference between revisions

From MoodleDocs
No edit summary
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Work in progress}}
== Introduction ==
== Introduction ==


Line 13: Line 15:
The gradebook import modules are located in the '''grade/import''' directory.  To create a new gradebook import module complete the steps listed below.
The gradebook import modules are located in the '''grade/import''' directory.  To create a new gradebook import module complete the steps listed below.


'''Note''': For the remainder of this topic when you see [newimport], replace it with the short name you chose for your export. Do not include the [].  Moodle comes with the following import modules: csv and xml so you cannot use those names.
'''Note''': For the remainder of this topic when you see [newimport], replace it with the short name you chose for your import module. Do not include the [].  Moodle comes with the following import modules: csv and xml so you cannot use those names.


=== New Gradebook Export Creation Steps ===
== New Gradebook Import Module Creation Steps ==


* Decide on a short name for this new import module.  This name will be referred to as [newimport] in this document.
* Decide on a short name for this new import module.  This name will be referred to as [newimport] in this document.
Line 21: Line 23:
* Review the import formats that ship with Moodle and choose the import format most like the one you wish to develop. Refer to that import's files as needed.
* Review the import formats that ship with Moodle and choose the import format most like the one you wish to develop. Refer to that import's files as needed.
* Copy the files from the import format you selected into your newly created directory of grade/import/[newimport]
* Copy the files from the import format you selected into your newly created directory of grade/import/[newimport]
* Alter each of the files listed below.
* Remove references to the import module you copied and alter each of the files listed below.
* Click on Notifications link in the Site Administration menu to go through the upgrade process (if one didn't happen automatically) and set up the permissions for your import module.
* Click on Notifications link in the Site Administration menu to go through the upgrade process (if one didn't happen automatically) and set up the permissions for your import module.
* Test, test, test - until your import module performs properly.
* Test, test, test - until your import module performs properly.
=== Remove References to the Original Import Module ===
You must make sure to replace all references to the import module you copied with the name of your new import module. In Linux you can use grep to look for references to the import module you copied. Equivalent commands exist for both Windows and Mac. The following is an example that will list all the places that "csv" appears in your new import module.
    grep -R "csv" ./grade/import/[newimport]/
=== Files That Need Special Attention ===
Some of the files need some thought about your requirements.
==== /grade/import/[newimport]/db/access.php ====
The access.php file makes your gradebook import module available to teachers and allows the security administrator to decide who can and cannot access the module.  See the "View role details" page in Site Administration > Users > Permissions > Define roles for more details.
Review access.php of both csv and xml import modules and decide which capabilities make sense for your import module.
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 believe your import module is ready to test.
'''Note''': The gradeimport_[newimport].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/import/[newimport]/index.php ====
When a user selects Import > [newimport] from the gradebook navigation drop down they will be taken to your import module's index.php. It typically displays a form to allow the user to upload the data that will be imported. You can use the class grade_import_form at /grade/import/grade_import_form.php or you can implement your own class. The csv import module uses the standard form. The xml import module implements its own form class which can be found at /grade/import/xml/grade_import_form.php. Make sure your index.php is instantiating the class you want to use.
=== Customise Your Import Module ===
At this point you should have an import module that functions however it will behave exactly the same as the module you copied. Now you can start making modifications and altering it to your requirements. Remember to refer to both the csv and xml import modules. They will hopefully provide guidance about how grade importing works and working with Moodle in general.


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

Latest revision as of 10:59, 30 January 2012

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.


Introduction

This document is for developers wanting to allow users to import Moodle grade information in a format that is not currently supported by Moodle. Here is another document if you are looking for an introduction to importing grades into Moodle

Moodle allows authorised users to import grade information. This can be used to transfer student grades from another piece of software into Moodle.

Since 1.9 the Moodle gradebook has provided support for the addition of plug-in import modules to allow Moodle to import grade information in new or custom formats. Moodle includes two default gradebook import modules, csv and xml.

This document describes how to implement a custom gradebook import plug-in.

Getting started

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

Note: For the remainder of this topic when you see [newimport], replace it with the short name you chose for your import module. Do not include the []. Moodle comes with the following import modules: csv and xml so you cannot use those names.

New Gradebook Import Module Creation Steps

  • Decide on a short name for this new import module. This name will be referred to as [newimport] in this document.
  • Create a new directory in Moodle's grade/import directory for your files.
  • Review the import formats that ship with Moodle and choose the import format most like the one you wish to develop. Refer to that import's files as needed.
  • Copy the files from the import format you selected into your newly created directory of grade/import/[newimport]
  • Remove references to the import module you copied and alter each of the files listed below.
  • Click on Notifications link in the Site Administration menu to go through the upgrade process (if one didn't happen automatically) and set up the permissions for your import module.
  • Test, test, test - until your import module performs properly.

Remove References to the Original Import Module

You must make sure to replace all references to the import module you copied with the name of your new import module. In Linux you can use grep to look for references to the import module you copied. Equivalent commands exist for both Windows and Mac. The following is an example that will list all the places that "csv" appears in your new import module.

    grep -R "csv" ./grade/import/[newimport]/

Files That Need Special Attention

Some of the files need some thought about your requirements.

/grade/import/[newimport]/db/access.php

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

Review access.php of both csv and xml import modules and decide which capabilities make sense for your import module.

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 believe your import module is ready to test.

Note: The gradeimport_[newimport].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/import/[newimport]/index.php

When a user selects Import > [newimport] from the gradebook navigation drop down they will be taken to your import module's index.php. It typically displays a form to allow the user to upload the data that will be imported. You can use the class grade_import_form at /grade/import/grade_import_form.php or you can implement your own class. The csv import module uses the standard form. The xml import module implements its own form class which can be found at /grade/import/xml/grade_import_form.php. Make sure your index.php is instantiating the class you want to use.

Customise Your Import Module

At this point you should have an import module that functions however it will behave exactly the same as the module you copied. Now you can start making modifications and altering it to your requirements. Remember to refer to both the csv and xml import modules. They will hopefully provide guidance about how grade importing works and working with Moodle in general.

See also