Development:Repository plugins

Audience:

Plug-in Developer

Related Documents:

• Repository API
• Repository Interface for Moodle/Course/User
• Use Case Number Attribution

Introduction

Requirement

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

First steps

1. create a folder for your plugin into moodle/repository/ (eg. moodle/repository/myplugin)
2. into this folder, create the following files:
   • repository.class.php
   • icon.png (icon displayed in the file picker)
3. create the language file:
   • moodle/lang/repository_myplugin

The 3 different parts to write

1. Administration: you can customise the way administrator/user can set their repositories.
2. File picker integration: the core of your plugin, it will manage communication between Moodle and the repository service, it will manage the display into the file picker
3. I18n: internationalization should be done at the same time as you're writting the other parts.

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.

In order to access to a flickr public account the plugin 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: "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 Repositories will have a specific email address. However it 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: //I tell the API that the repositories have general settings: "api_key"

   public static function get_type_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 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?: 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 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. I'm done with the administration part of my Flickr Public plugin. For your information, Box.net, Flickr, and Flickr Public have been created in the same time that the API, have a look. Enjoy your coding.

Methods

All these methods are optional. If you don't implement any of these functions your plugin will not manual settings and 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 return an empty array, the API will consider that the plugin displays only one repository into the file picker. Parent function return an empty array.

instance_config_form(&$mform)

You can modify 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)

You can modify 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 add the plugin. So except if the administrator delete the plugin and re-add it, it should be called only one time. Parent function does nothing.

APIs for File picker

Methods 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)
    *       )
    *     ),
    *   )
    * )

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

I18n - Internationalization

These following strings are mandatory (moodle/lang/en_utf8/repository_myplugin)

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

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)

Functional Specifications

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