Repository plugins

A guide for developers on how to create a repository plugin.

Introduction

Prerequisites

Before starting coding, it is necessary to know how to use repository administration pages and how to use the file picker.

First steps

1. Create a folder for your plugin in moodle/repository/ e.g. moodle/repository/myplugin
2. Create the following files and add them to the plugin folder:
   • repository.class.php
   • icon.png (the icon displayed in the file picker)
3. Create the language file repository_myplugin.php and add it to the plugin folder, keeping the following folder structure:
   • moodle/repository/myplugin/lang/en_utf8/repository_myplugin.php

Overview

The 3 different parts to write

1. Administration - You can customise the way administrators and users can configure their repositories.
2. File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
3. I18n - Internationalization should be done at the same time as you're writing the other parts.

Administration APIs

As an example, let's create a Flickr plugin for accessing a public flickr account. The plugin will be called "Flickr Public".

Firstly the 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 {
   }

?>

Then consider the question "What does my plugin do?"

In the Moodle file picker, we 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 clicks on one of these repositories, the public pictures are displayed in the file picker.

In order to access to a flickr public account, the plugin needs 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.

//We tell the API that the repositories have specific settings: "email address"

   public static function get_instance_option_names() {
       return array('email_address');
   }

//We 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 our Flickr Public Repositories will have a specific email address. However this is not enough. 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 add settings to the plugin level, impacting all repositories. The code is similar the repository instance settings: //We tell the API that the repositories have general settings: "api_key"

   public static function get_type_option_names() {
       return array('api_key');
   }

//We add an "api key" text box to the create/edit repository plugin Moodle form (also called a Repository type Moodle form)

   public function type_config_form(&$mform) {
       //the following line is needed in order to retrieve the API key value 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?

Yes! We have created everything necessary for the administration pages. But let's go further. It would be good if the user can enter any "Flickr public account email address" in the file picker. In fact we want to display in the file picker a Flickr Public repository that the Moodle administrator can never delete. Let's add:

    //this function is only called one time, when the Moodle administrator add the Flickr Public Plugin into the Moodle site.
    public static function plugin_init() {
       //here we create a default repository instance. The last parameter 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);
    }

That's all - the administration part of our Flickr Public plugin is done. For your information, Box.net, Flickr, and Flickr Public all have similar administration APIs.

Functions

All of the following functions are optional. If they're not implemented, your plugin will not have manual settings and will have only one instance (which is created automatically).

get_instance_option_names

This function must be declared static
Return an array of strings. These strings are setting names. These settings are specific to an instance. If the function returns an empty array, the API will consider that the plugin displays only one repository in the file picker. Parent function returns an empty array.

instance_config_form(&$mform)

This is for modifying the Moodle form displaying the settings specific to an instance.

For example, to add a required text box called email_address: $mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public')); $mform->addRule('email_address', $strrequired, 'required', null, 'client');

Note: mform has by default a name text box (cannot be removed).

Parent function does nothing.

get_type_option_names

This function must be declared static
Return an array of string. These strings are setting names. These settings are shared by all instances. Parent function return an empty array.

type_config_form(&$mform)

This is for modifying the Moodle form displaying the plugin settings. Similar to instance_config_form(&$mform)

plugin_init()

This function must be declared static
This function is called when the administrator adds the plugin. So unless the administrator deletes the plugin and re-adds it, it should be called only once. Parent function does nothing.

File picker APIs

Functions you *MUST* override

__construct

You may initialize your plugin here, such as:

1. Get options from database
2. 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)
    *       )
    *     ),
    *   )
    * )

Functions you can override

print_login

This function will help to print a login form, for the 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 a user clicks the logout button in file picker, this function will be called. You may clean up the session or disconnect the 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 a user clicks the 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 a user clicks the "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 it to a better location.

get_name

This function will return the name of the repository instance.

I18n - Internationalization

These following strings are required in moodle/repository/myplugin/lang/en_utf8/repository_myplugin.php:

$string['configplugin'] = 'Flickr Public configuration'; $string['repositorydesc'] = 'A Flickr public repository'; $string['repositoryname'] = 'Flickr Public';

Standard repository plugins

This is the functional specification list of the officially supported repository plugins. For each plugins, the two mains part we are interested in are:

• How do I administrate the plugin? See Repository Administration Specification - UC001-3
• How do I set up an account for this repository? See Repository Interface for Moodle/Course/User

Functional specifications

• Box.net Repository Plugin
• Flickr Repository Plugin
• Moodle Local Repository Plugin
• Moodle MNET Repository Plugin

See also

• Repository API
• Repository Interface for Moodle/Course/User
• Use Case Number Attribution
• MDL-16543 - A list of officially supported repository plugins