Development: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.

There is a template attached to MDL-16543 which might be useful to help get you started.

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:
   • lib.php
   • pix/icon.png (the icon displayed in the file picker)
   • "version.php"
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/repository_myplugin.php or moodle/lang/en/repository_myplugin.php
4. Create access.php and upgrade scripts

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 key (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 displayed in the File Picker (The repository API creates this unique instance when the administrator add the plugin).

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

Quick Start

To be completed
First of all, the File Picker using intensively Ajax you will need a easy way to debug. Install FirePHP (MDL-16371) and make it works. It will save you a lot of time. (You might give the FirePHP plugin for Moodle a try, it's still work in progress, though.)

Your first question when you write your plugin specification is 'Does the user need to log-in'?
.....

For most of plugins, you need to establish a connection with the remote repository. This connection can be done into the get_listing(), constructor() function...
.....

You wanna display a list of files once the user is logged
.... get_listing() .....

You wanna retrieve the file that the user selected
....

Optional question that you should ask yourself is 'Does the user can execute a search'
.... search() ....

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($path="", $page="")

This function will return a list of files, the list must be a array like this: $list = array(

//this will be used to build navigation bar

'path'=>array(array('name'=>'root','path'=>'/'), array('name'=>'subfolder', 'path'=>'/subfolder')), 'manage'=>'http://webmgr.moodle.com', 'list'=> array(

   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 of list element:

array(
  // Used to build navegation bar, so you need to include all parents folders
  // array(array('name'=>'root','path'=>'/'), array('name'=>'subfolder', 'path'=>'/subfolder'))
  'path' => (array) this will be used to build navigation bar
  // dynload tells file picker to fetch list dynamically, when user click
  // the folder, it will send a ajax request to server side.
  // if you are using pagination, 'page' and 'pages' parameters should be used
  // and note, you'd better don't use pagination and page at the same time
  'page' => (int) which page is this list
  'pages' => (pages) how many pages
  'dynload' => (bool) use dynamic loading,
  // will display a link in file picker
  'manage' => (string) url of the file manager,
  // set to true, the login link will be removed from file picker
  'nologin' => (bool) requires login,
  // set to true, the search link will be removed from file picker
  'nosearch' => (bool) no search link,
  // set this option will display a upload form in file picker
  // only used in upload plugin currently
  'upload' => array( // upload manager
    'label' => (string) label of the form element,
    'id' => (string) id of the form element
  ),
  // file picker will build a file tree according this 
  // list
  'list' => array(
    array( // file
      'title' => (string) file name,
      'shorttitle' => (string) optional, if you prefer to display a short title
      'date' => (string) file last modification time, usually userdate(...),
      'size' => (int) file size,
      'thumbnail' => (string) url to thumbnail for the file,
      'thumbnail_width' => (int) the width of the thumbnail image,
      '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,
      'shorttitle' => (string) optional, if you prefer to display a short title
      '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)
      )
    ),
  )
)

Dynamically loading Some repositories contain many files which cannot load in one time, in this case, we need dynamically loading to fetch them step by step, files in subfolder won't be listed until user click the folder in file picker treeview.

As a plug-in developer, if you set dynload flag as true, you should return files and folders (set children as a null array) in current path instead of building the whole file tree.

Example of dynamically loading See Alfresco plug-in

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);
           // if you are going to rename submit button label, use this option
           //$ret['login_btn_label'] = get_string('submit_btn_label');
           // if you are going to display a search form instead of login form
           // set this option to true
           //$ret['login_search_form'] = true;
           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.

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 or moodle/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 administer 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
• Remote Moodle 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
• MDL-16543 - Template plugin for developers