Repository plugins
Audience:
- Plug-in Developer
Related Documents:
Introduction
In order to create your repository plugin, you will need to create a main class containing different methods some mandatory and other optional. It is mandatory for you to know how to use repository administration pages and how to use the file picker.
APIs for Administration
Quick Start
As a Quick Start I will create a Flickr Plugin. This plugin will be used to access to a public flickr account. I will call my plugin Flickr Public.
Let's create my skeleton:
<?php
/**
* repository_flickr_public class
* Moodle user can access public flickr account
*
* @license http://www.gnu.org/copyleft/gpl.html GNU Public License
*/
class repository_flickr_public extends repository {
}
?>
What does my plugin do ?: in the Moodle file picker, I want to display some flickr public repositories directly linked to a flickr public account. For example My Public Flickr Pictures, and also My Friend's Flickr Pictures. When the user click one of these repositories, the public pictures are displayed into the file picker.
So the file picker will display multiple Flickr Public repositories (also called instance). I add into my class:
public static function has_multiple_instances() {
return true;
}
In order to access to a flickr public account you need to know the email address of the Flickr public account owner. So the administrator will need to set an email address for every repository. Let's add an "email address" setting to every repository.
//I tell the API that the repositories have specific settings
public static function has_instance_config() {
return true;
}
//I tell the API that all my repository instance have an "email address"
public static function get_instance_option_names() {
return array('email_address');
}
//I add an "email address" text box to the create/edit repository instance Moodle form
public function instance_config_form(&$mform) {
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', get_string('required'), 'required', null, 'client');
}
So at this moment all my Flickr Public Repository will have a specific email address. However in order to communicate with Flickr, Moodle needs to know a Flickr API (http://www.flickr.com/services/api/). This API key is the same for any repository. We could add it with the email address setting but the administrator would have to enter the same API key for every repository. Hopefully the administrator can set settings for the plugin, impacting all repositories. The code is similar the repository instance settings:
//I tell the API that the repositories share general settings
public static function has_admin_config() {
return true;
}
//I tell the API that the general settings are: "api_key"
public static function get_admin_option_names() {
return array('api_key');
}
//I add an "api key" text box to the create/edit repository plugin Moodle form (also called as Repository type Moodle form)
public function admin_config_form(&$mform) {
//the following line is needed in order to retrieve the API key from the database when Moodle displays the edit form
$api_key = get_config('flickr_public', 'api_key');
$mform->addElement('text', 'api_key', get_string('apikey', 'repository_flickr_public'),
array('value'=>$api_key,'size' => '40'));
$mform->addRule('api_key', get_string('required'), 'required', null, 'client');
}
Have we finished yet: in fact, yes! We created all that we need for the administration pages. But let's go further. It would be good that the user can enter any "Flickr public account email address" into the file picker. In fact we want to display into the file picker a Flickr Public repository that the Moodle administrator can not delete. Let's add:
//this function is called when the Moodle administrator will add the Flickr Public Plugin into the Moodle site.
public static function plugin_init() {
//here we create a default instance, last param is 1 in order to set the instance as readonly.
repository_static_function('flickr_public','create', 'flickr_public', 0, get_system_context(),
array('name' => 'default instance','email_address' => null),1);
}
Methods
All these methods are optional.
public static function has_multiple_instances()
Return true if you'd like to display multiple repositories into the file picker (for example Repository of Martin, Repository of Jerome,...). Parent function return false.
public static function has_instance_config()
Most of the time if your plugin supports multiple instances, you will want to have different settings per instance. In this case this function should return true. Parent function return false.
public static function get_instance_option_names()
Return an array of string. The strings are the name of your instance settings. Parent function return an empty array.
public function instance_config_form(&$mform)
You can modify the Moodle form displaying the instance settings.
For example, to add a required text box called public_url:
$mform->addElement('text', 'public_url', get_string('publicurl', 'repository_boxnet'));
$mform->addRule('public_url', $strrequired, 'required', null, 'client');
Note: mform has by default a name text box (cannot be removed).
Parent function does nothing.
public static function has_admin_config()
Do you want to set some config share by all repository instances (for example an API key). If yes return true. Parent function return false
public static function get_admin_option_names()
Return an array of string. The strings are the name of the plugin settings. Parent function return an empty array.
public function admin_config_form(&$mform)
Similar to instance_config_form(&$mform) for plugin settings.
public static function plugin_init()
This function is called when the administrator add a new plugin. So except if the administrator delete the plugin and readd it, it should be call only one time. It's for example a good place in order to create default instance. Parent function does nothing.
APIs for File picker
Methods you *MUST* override
__construct
You may initialize your plugin here, such as:
- Get options from database
- Get user name and password from HTTP POST.
get_listing
This function will return a list of files, the list must be a array like this:
$list = array(
'path'=>'/var/repo/',
'manage'=>'http://webmgr.moodle.com',
array('title'=>'filename1', 'date'=>'01/01/2009', 'size'=>'10MB', 'source'=>'http://www.moodle.com/dl.rar'),
array('title'=>'folder', 'date'=>'01/01/2009', 'size'=>'0', 'children'=>array())
);
The full specification:
* array(
* 'path' => (string) path for the current folder
* 'dynload' => (bool) use dynamic loading,
* 'manage' => (string) link to file manager,
* 'nologin' => (bool) requires login,
* 'nosearch' => (bool) no search link,
* 'search_result' => (bool) this list is a searching result,
* 'upload' => array( // upload manager
* 'name' => (string) label of the form element,
* 'id' => (string) id of the form element
* ),
* 'list' => array(
* array( // file
* 'title' => (string) file name,
* 'date' => (string) file last modification time, usually userdate(...),
* 'size' => (int) file size,
* 'thumbnail' => (string) url to thumbnail for the file,
* 'source' => plugin-dependent unique path to the file (id, url, path, etc.),
* 'url'=> the accessible url of file
* ),
* array( // folder - same as file, but no 'source'.
* 'title' => (string) folder name,
* 'path' => (string) path to this folder
* 'date' => (string) folder last modification time, usually userdate(...),
* 'size' => 0,
* 'thumbnail' => (string) url to thumbnail for the folder,
* 'children' => array( // an empty folder needs to have 'children' defined, but empty.
* // content (files and folders)
* )
* ),
* )
* )
Methods you can override
print_login
This function will help to print a login form, for ajax file picker, this function will return a
PHP array to define this form.
public function print_login(){
if ($this->options['ajax']) {
$user_field->label = get_string('username', 'repository_boxnet').': ';
$user_field->id = 'box_username';
$user_field->type = 'text';
$user_field->name = 'boxusername';
$user_field->value = $ret->username;
$passwd_field->label = get_string('password', 'repository_boxnet').': ';
$passwd_field->id = 'box_password';
$passwd_field->type = 'password';
$passwd_field->name = 'boxpassword';
$ret = array();
$ret['login'] = array($user_field, $passwd_field);
return $ret;
}
}
This will help to generate a form by file picker which contains user name and password input elements.
If your plugin don't require logging in, you don't need to override it, it will call get_listing to list files automatically by default.
check_login
This function will return a boolean value to tell moodle whether the user has logged in. By default, this function will return true.
logout
When user clicked logout button in file picker, this function will be called, you may clean up session or disconnect connection with remote server here.
global_search
Moodle Repository API supports global search, this function will return a boolean value to tell Moodle if this plugin is ready to search, by default, it will return false, you need to override it to enable global search.
print_search
When user clicked search button on file picker, this function will be called to return a search form, by default, it will create a form with single search bar, you can override it to create a advanced search form.
search
This function will do the searching job, you can obtain the POST parameters from the from the form you created in print_search function This function will return a file list exactly like the one from get_listing.
get_file
When user clicked "Get" button to transfer the file, this function will be called, basically, it will download a file to Moodle, you can override it to modify the file then move to a proper location.
get_name
This function will return the name of the repository instance
Officially supported repository plugins list
See: http://tracker.moodle.org/browse/MDL-16543
Standard repository plugins
This is the functional specification list of the officially supported repository plugins. For each plugins, the two mains part we are interesting in are:
- How do I administrate the plugin ( Repository Administration Specification - UC001-3)
- How do I setup an account for this repository ( Repository Interface for Moodle/Course/User)
