Charts API

2016-11-29T07:41:43Z

Lameze: /* Axis position */

Charts API

2016-11-29T07:25:55Z

Lameze: /* Axis */

Charts API

2016-11-29T06:12:57Z

Lameze: /* Renderering */

Authentication plugins

2015-10-06T07:34:28Z

Lameze:

==Introduction==

This page first gives an '''overview''' of the ''authentication process'' and then explains how ''authentication modules'' can be '''created''' using hooks to take over from the native authentication in Moodle.
=== Overview of Moodle authentication process ===
[[File:1.9.11_login_element.png|203px||thumb|right|The login UI element in Moodle 1.9]]The authentication use case in Moodle starts when a user clicks on the Login link in the UI or if they try to access a protected page. There are two broad classes of authentication plugins, the regular type where moodle handles the password and ones where the password is handled by a 3rd party page eg SAML, OpenID etc.

For the regular plugins the following happens (skipping some minor details and rarer scenarios):

# The default login page (<tt>/login/index.php</tt>) is displayed. OR, if a system administrator has set the Alternate Login URL on the "Manage authentication" page, that URL will be displayed.
# A user enters their credentials and submits the form.
# The handler code in <tt>/login/index.php</tt> runs:
## Gets a list of enabled authentication plugins.
## Runs <tt>loginpage_hook()</tt> for each plugin, in case any of them needs to intercept the login request.
## Checks to make sure that the username meets Moodle's criteria (alphanumeric, with periods and hyphens allowed).
## Calls <tt>authenticate_user_login()</tt> in <tt>/lib/moodlelib.php</tt>, which returns a <code>$user</code> object. (Details of this code follow this main outline.)
## Determines whether authentication was successful (by checking whether <code>$user</code> is a valid object) and, if not, sends them back to the login page with an error message. Otherwise, it figures out where to send the user based on their original page request, whether their password is expired, etc., and redirects them there.

For the 3rd party auth plugins the process could look like this (eg CAS, SAML, OpenID etc):
# Access a protected page but isn't logged in, so moodle calls <tt>pre_loginpage_hook()</tt> on each enabled plugin, which may redirect to the 3rd party login page
# Or if they go directly to the login page moodle calls <tt>loginpage_hook()</tt> on each enabled plugin, which may redirect to the 3rd party login page
# The user enters their credentials and authenticates on the 3rd party page
# The remote authentication service redirects back to moodle with an assertion, such as a single use token or encrypted response in a query param
# The auth plugin now validates the token or decrypts the assertion, does any other checking as required and then logs the user in using <tt>complete_user_login($user)</tt>. If this happens inside <tt>pre_loginpage_hook()</tt> then the user continues on their way, or if inside <tt>loginpage_hook()</tt> or another custom page then the plugin should redirect to the wantsurl.

Note that in this scenario above <tt>user_login($username, $password)</tt> is never called and should probably return false.

==History==
Authentication plugins exist from 1.9
==Example==
[http://moodle.org/plugins/view.php?plugin=auth_googleoauth2 Google / Facebook / Messenger Oauth2 Authentication plugin]

==Template==
Please see Moodle '''none''' authentication plugin (auth/none), it's the perfect plugin template to start with.

==Naming convention==
==File structure==
# Choose a name for your plugin. We'll use 'sentry' as an example below; change it to whatever name you have chosen.
# Under your Moodle installation root, create the directory <tt>/auth/sentry</tt>. It should be sibling to existing auth plugin directories: 'db', 'nologin', 'none', etc.
# Create the file <tt>/auth/sentry/auth.php</tt>. Within the file, create a class <tt>auth_plugin_sentry</tt> that extends <tt>auth_plugin_base</tt> from <tt>/lib/authlib.php</tt>. (You will need to <code>require_once</code> the authlib file.)
# Implement the <tt>user_login()</tt> function in your <tt>auth.php</tt> file, and create or override additional functions based on your plugin's requirements.
# Log in to your Moodle installation as a site administrator and find, in the site administrator block, the page "Users -> Authentication -> Manage authentication". You will see your plugin in the list, appearing as <nowiki>[[auth_sentrytitle]]</nowiki>. You can enable it and move it up and down in the order. '''At this point, with the plugin enabled, your plugin is registered and will be used by Moodle in its authentication process.'''
# If you don't like seeing <nowiki>[[auth_sentrytitle]]</nowiki> as the name of your plugin in the Moodle UI, you'll need to create language files for your plugin. Do this by creating the directory <tt>/auth/sentry/lang</tt>, and under it, a directory for each language that your installation needs to support. (Example: <tt>/auth/sentry/lang/en</tt>.) Within each of these language directories, create a file called <tt>auth_sentry.php</tt>. That file should set the desired value for <code>$string['auth_sentrytitle'] for that language (use $string['pluginname'] for Moodle2)</code>. You can also set the plugin description by setting <code>$string['auth_sentrydescription']</code>, and you can also assign other translatable strings that your plugin uses, in these files. '''Note:''' A folder named like '''en''' may not work for everyone. Please refer to the lang folder under your moodle installation directory to get an idea about the language/locale codes used in your moodle installation. For example, the lang folder in own users system contained folders named '''en''' and '''zh-cn'''. He emulated the same in the lang folder of the auth plugin and the plugin picked up the title and description strings immediately. ([[Places_to_search_for_lang_strings|More info on how Moodle handles language]]).
# If you want to configure your plugin through the Moodle UI, implement <tt>config_form()</tt> and <tt>process_config()</tt> in the plugin class. You might find it convenient to use the 'db' plugin as a model for this. The plugin's config settings can then be managed through the Manage authentication page by clicking on the Settings link for that plugin, and the values will be stored in the <tt>mdl_config_plugins</tt> table in the database.

==Interfacing to API's==

=== <tt>authenticate_user_login()</tt>===
That's the main outline, but a lot of interesting stuff happens in <tt>authenticate_user_login()</tt>:

# It gets a list of enabled authentication plugins.
# It looks up the username in the mdl_user table to see if they are allowed to log in, and which authentication plugin handles their login requests. (This will be the plugin that handled their first-ever login request.)
# It creates a user object, which will contain the data from <tt>mdl_user</tt> if the username is known; if not, it will be an empty object.
# It does the following with the authentication plugin (note that for a username unknown to Moodle, it will do these steps for each authenticated plugin until one succeeds or it has tried them all):
## Calls the <tt>user_login()</tt> function provided by that plugin, which returns a boolean value based on whether the credentials authenticate or not. If the result is false (not authenticated), skips the rest of the steps below and continues to the next plugin.
## If the plugin authenticates against an external system (not Moodle's user database), its <tt>update_user_record()</tt> function is called to get the user's name, contact info, etc.
## Creates the Moodle user record if it doesn't already exist.
## Calls the plugin's <tt>sync_roles()</tt> function.
## Notifies each enabled authentication plugin that the user successfully authenticated, by calling each one's <tt>user_authenticated_hook()</tt> function.
# It returns the user object if everything was successful, or false if no plugin was able to successfully authenticate the credentials.

=== <tt>user_login($username, $password)</tt>===
This must be rewritten by plugin to return boolean value, returns true if the username and password work and false if they are wrong or don't exist.

=== <tt>can_change_password()</tt>===
Returns true if this authentication plugin can change users' password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>change_password_url()</tt>===
Returns the URL for changing the users' passwords, or empty if the default URL can be used.

=== <tt>can_edit_profile()</tt>===
Returns true if this authentication plugin can edit the users' profile.

; '''Return type''' : boolean
; '''Default return value''' : true

=== <tt>edit_profile_url()</tt>===
Returns the URL for editing users' profile, or empty if the defaults URL can be used.

=== <tt>is_internal()</tt>===
Returns true if this authentication plugin is "internal". Internal plugins use password hashes from Moodle user table for authentication.

; '''Return type''' : boolean
; '''Default return value''' : true

=== <tt>prevent_local_passwords()</tt>===
Indicates if password hashes should be stored in local moodle database. This function automatically returns the opposite boolean of what is_internal() returns. Returning true means MD5 password hashes will be stored in the user table. Returning false means flag 'not_cached' will be stored there instead.

; '''Return type''' : boolean
; '''Default return value''' : !$this->is_internal()

=== <tt>is_synchronised_with_external()</tt>===
Indicates if moodle should automatically update internal user records with data from external sources using the information from get_userinfo() method. This function automatically returns the opposite boolean of what is_internal() returns.

; '''Return type''' : boolean
; '''Default return value''' : !$this->is_internal()

=== <tt>user_update_password($user, $newpassword)</tt>===
Update the user's password.

=== <tt>user_update($olduser, $newuser)</tt>===
Called when the user record is updated. It will modify the user information in external database.

=== <tt>user_delete($olduser)</tt>===
User delete requested. Internal user record had been deleted.

=== <tt>can_reset_password()</tt>===
Returns true if plugin allows resetting of internal password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>can_signup()</tt>===
Returns true if plugin allows resetting of internal password.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>user_signup($user, $notify=true)</tt>===
Sign up a new user ready for confirmation, password is passed in plaintext.

=== <tt>can_confirm()</tt>===
Returns true if plugin allows confirming of new users.

; '''Return type''' : boolean
; '''Default return value''' : false

=== <tt>user_confirm($username, $confirmsecret)</tt>===
Confirm the new user as registered.

=== <tt>user_exists($username)</tt>===
Checks if user exists in external db.

=== <tt>password_expire($username)</tt>===
Returns number of days to user password expires.

=== <tt>sync_roles()</tt>===
Sync roles for this user - usually creator

=== <tt>get_userinfo($username)</tt>===
Read user information from external database and returns it as array.

=== <tt>config_form($config, $err, $user_fields)</tt>===
Prints a form for configuring this authentication plugin. It's called from admin/auth.php, and outputs a full page with a form for configuring this plugin.

=== <tt>validate_form($form, $err)</tt>===
Validate form data.

=== <tt>process_config($config)</tt>===
Processes and stores configuration data for this authentication plugin.

=== <tt>loginpage_hook()</tt>===
Hook for overriding behaviour of login page.

=== <tt>pre_loginpage_hook()</tt>===
Hook for overriding behaviour of prior to redirecting to the login page, eg redirecting to an external login url for SAML or OpenID authentication. If you implement this you should also implement loginpage_hook as the user may go directly to the login page.

=== <tt>user_authenticated_hook($user, $username, $password)</tt>===
Post authentication hook. This method is called from authenticate_user_login() for all enabled auth plugins.

=== <tt>prelogout_hook()</tt>===
Pre logout hook.

=== <tt>postlogout_hook()</tt>===
This replace the prelogout_hook method to avoid authentication plugins redirects before the event userlogout being triggered.
At the moment the only authentication plugin using this method is CAS (SSO).

=== <tt>logoutpage_hook()</tt>===
Hook for overriding behaviour of logout page.

=== <tt>can_be_manually_set()</tt> ===
This function was introduced in the base class and returns false by default. If overriden by an authentication plugin to return true, the authentication plugin will be able to be manually set for users. For example, when bulk uploading users you will be able to select it as the authentication method they use.

==See also==

* [[Authentication API]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=102070 Overview of entire authentication code flow] forum discussion
* Using Moodle [http://moodle.org/mod/forum/view.php?id=42 User authentication forum]
* Moodle Docs [[:en:Manage authentication|Manage authentication]]
* [[:en:Authentication FAQ|Authentication FAQ]]

[[Category:Authentication]]
[[Category:Plugins]]

[[fr:Méthodes_d'authentification]]

Developer meeting July 2015

2015-07-20T01:36:11Z

Lameze: /* Agenda */

[[Developer meetings]] > July 2015 meeting notes

{| class="nicetable"
|-
| Time
| [http://www.timeanddate.com/worldclock/fixedtime.html?year=2015&month=7&day=21&hour=07&min=0&sec=0 07:00 UTC on Tuesday, 21 July 2015] [http://www.google.com/calendar/event?action=TEMPLATE&text=Moodle+General+developer+meeting&dates=20150721T070000Z/20150721T090000Z&details=&location= <span class="btn btn-info">Add to my calendar</span>]
|-
| Meeting room
| [https://www.youtube.com/watch?v=pgPBohzErr4 Live stream at YouTube]
|-
| Forum discussion
| [https://moodle.org/mod/forum/discuss.php?d=316807 Thread in GDF at moodle.org]
|-
| Chat
| [https://moodle.org/local/chatlogs/info.php Regular dev chat]
|-
| Twitter
| [https://twitter.com/search?q=%23moodledev #moodledev]
|-
| Social event page
| [https://plus.google.com/events/c63rl8n5jdjldr9slcd1tdcqmg0 Google+ page]
|-
| Meeting notes
| [https://devpad.moodle.org/p/gdm150721 devpad]
|}

== Agenda ==

* Moodle Mobile 2 - Juan Leyva
* Summary report of the recent Moodle hackfests (Dublin, Melbourne) - David Mudrák, Andrew Nicols
* Moodle Association and how it is supposed to affect the Moodle development in the future - Martin Dougiamas
* Moodle HQ's personal projects week products - HQ devs
** Improved East Asian support (ruby tags in Atto and in fullname()) - Jetha Chan
** mod_lesson improved lesson creation tool - Adrian Greeve
** Events Graphic Reports plugin - Simey Lameze
* Work in progress on Learning plans and outcomes project for Moodle 3.0 - Damyon (to be confirmed)
* ...

Please feel encouraged to raise topics you would like to present / discuss during the meeting. Contact [https://moodle.org/user/profile.php?id=1601 David Mudrák] for details.

Gradebook export

2015-05-06T07:10:24Z

Lameze: /* /grade/export/[newexport]/index.php */

== 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 [https://docs.moodle.org/en/Grade_export 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 Module 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.

=== Files That Need Special Attention ===

==== /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 checks:

require_capability('gradeexport/[newexport]:publish', $context);
require_capability('gradeexport/[newexport]:view', $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 <nowiki>[[modulename]]</nowiki>. 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';

=== A Safety Check For References to the Original Export Module ===
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 Module ===

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]]
* [[Gradebook_import]]

[[Category:Grades]]
[[Category:Plugins]]

Gradebook export

2015-05-06T07:09:58Z

Lameze: /* /grade/export/[newexport]/grade_export_[newexport].php */

== 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 [https://docs.moodle.org/en/Grade_export 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 Module 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.

=== Files That Need Special Attention ===

==== /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 checks:

require_capability('gradeexport/[newexport]:publish', $context);
require_capability('gradeexport/[newexport]:view', $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 <nowiki>[[modulename]]</nowiki>. 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';

=== A Safety Check For References to the Original Export Module ===
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 Module ===

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]]
* [[Gradebook_import]]

[[Category:Grades]]
[[Category:Plugins]]

Gradebook export

2015-05-06T07:09:39Z

Lameze: /* /grade/export/[newexport]/export.php */

== 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 [https://docs.moodle.org/en/Grade_export 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 Module 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.

=== Files That Need Special Attention ===

==== /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 checks:

require_capability('gradeexport/[newexport]:publish', $context);
require_capability('gradeexport/[newexport]:view', $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 <nowiki>[[modulename]]</nowiki>. 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';

=== A Safety Check For References to the Original Export Module ===
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 Module ===

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]]
* [[Gradebook_import]]

[[Category:Grades]]
[[Category:Plugins]]