Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Repository plugins: Difference between revisions

From MoodleDocs
(→‎Administration APIs: Rearranged and expanded the explanations slightly)
Line 89: Line 89:


====type_config_form($mform, $classname='repository')====
====type_config_form($mform, $classname='repository')====
This is for modifying the Moodle form displaying the plugin settings. [[lib/formslib.php Form Definition]] has details of all the types of elements you can add to the settings form.
Optional. This is for modifying the Moodle form displaying the plugin settings. [[lib/formslib.php Form Definition]] has details of all the types of elements you can add to the settings form.


For example, to display the standard repository plugin settings along with the custom ones use:
For example, to display the standard repository plugin settings along with the custom ones use:
Line 103: Line 103:


====type_form_validation($mform, $data, $errors)====
====type_form_validation($mform, $data, $errors)====
Use this function if you need to validate some variables submitted by plugin settings form. To use it, check through the associative array of data provided ('settingname' => value) for any errors. Then push the items to $error array in the format ("fieldname" => "human readable error message") to have them highlighted in the form.
Optional. Use this function if you need to validate some variables submitted by plugin settings form. To use it, check through the associative array of data provided ('settingname' => value) for any errors. Then push the items to $error array in the format ("fieldname" => "human readable error message") to have them highlighted in the form.


With the example above, this function may look like:
With the example above, this function may look like:

Revision as of 10:32, 5 December 2012

Introduction

Repository plugin allow Moodle to bring contents into Moodle from external repositories.

Prerequisites

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

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.

History

Repository plugins exists from 2.0

Example

Template

There is a template available in Dongsheng Cai's github

Creating new repository plugin

  1. Create a folder for your plugin in /repository/ e.g. /repository/myplugin
  2. Create the following files in your plugin folder:
    • /repository/myplugin/lib.php
    • /repository/myplugin/pix/icon.png - the icon displayed in the file picker (16x16)
    • /repository/myplugin/version.php
    • /repository/myplugin/lang/en/repository_myplugin.php - language file
    • /repository/myplugin/db/access.php
  3. Declare class repository_myplugin extends repository in your lib.php
  4. In your repository_myplugin class overwrite function get_listing() to return array('list' => array());
  5. Add at least strings $string['pluginname'] and $string['configplugin'] to your language file
  6. Add capability 'repository/myplugin:view' to your access.php file
  7. Create install and upgrade scripts (optional or you can do it later)
  8. Login as admin on your website and run upgrade
  9. Open Site Administration->Plugins->Repositories->Manage Repositories and make your repository 'Enabled and visible'

For a more detailed explanation of each of each of the files that have been created here, along with code examples, see Repository plugin files.

Administration APIs

Fixed settings

These are settings that are hard-coded into your repository plugin and can only be updated by changing the plugin code.

supported_returntypes()

Return any combination of the following values:

  • FILE_INTERNAL - the file is uploaded/downloaded and stored directly within the Moodle file system
  • FILE_EXTERNAL - the file stays in the external repository and is accessed from there directly
  • FILE_REFERENCE - the file may be cached locally, but is automatically synchronised, as required, with any changes to the external original

The type used by Moodle depends on the choices made by the end user (e.g. inserting a link, will result in 'FILE_EXTERNAL'-related functions being used, using a 'shortcut/alias' will result in the 'FILE_REFERENCE'-related functions being used). function supported_returntypes() {

   return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;

}

supported_filetypes()

Optional. Returns '*' for all file types (default implementation), or an array of types or groups (e.g. array('text/plain', 'image/gif', 'web_image') ) function supported_filetypes() {

   //return '*';
   //return array('image/gif', 'image/jpeg', 'image/png');
   return array('web_image');

} For a full list of possible types and groups, look in lib/filelib.php, function get_mimetypes_array().

Global settings

These are settings that are configured for the whole Moodle site and not per instance of your plugin. All of these are optional, without them there will be no configuration options in the Site administration > Plugins > Repositories > Myplugin page.

get_type_option_names()

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

For example: public static function get_type_option_names() {

  return array_merge(parent::get_type_option_names(), array('rootpath'));

}

type_config_form($mform, $classname='repository')

Optional. This is for modifying the Moodle form displaying the plugin settings. lib/formslib.php Form Definition has details of all the types of elements you can add to the settings form.

For example, to display the standard repository plugin settings along with the custom ones use: public function type_config_form($mform) {

   parent::type_config_form($mform);
   $rootpath = get_config('repository_someplugin', 'rootpath');
   $mform->addElement('text', 'rootpath', get_string('rootpath', 'repository_someplugin'), array('size' => '40'));
   $mform->setDefault('rootpath', $rootpath);

}

type_form_validation($mform, $data, $errors)

Optional. Use this function if you need to validate some variables submitted by plugin settings form. To use it, check through the associative array of data provided ('settingname' => value) for any errors. Then push the items to $error array in the format ("fieldname" => "human readable error message") to have them highlighted in the form.

With the example above, this function may look like: public static function type_form_validation($mform, $data, $errors) {

   if (!is_dir($data['rootpath'])) {
       $errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
   }
   return $errors;

}

Instance settings

These functions relate to a specific instance of your plugin (e.g. the URL and login details to access a specific webdav repository).

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. This is equivalent to get_type_option_names(), but for a specific instance. public static function get_instance_option_names() {

   return array('fs_path'); // From repository_filesystem

}

instance_config_form($mform)

This is for modifying the Moodle form displaying the settings specific to an instance. This is equivalent to type_config_form($mform, $classname) but for instances.

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.

instance_form_validation($mform, $data, $errors)

This allows us to validate what has been submitted in the instance configuration form. This is equivalent to type_form_validation($mform, $data, $errors), but for instances. For example: public static function instance_form_validation($mform, $data, $errors) {

   if (empty($data['email_address'])) {
       $errors['email_address'] = get_string('invalidemailsettingname', 'repository_flickr_public');
   }
   return $errors;

}

Getting / updating settings

Both global and instance settings can be retrieved, from within the plugin, via $this->get_option('settingname') and updated via $this->set_option(array('settingname' => 'value')).

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.


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.

Repository APIs

Quick Start

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'? If they do, in your plugin you have to detect user session in constructor() function, and use print_login() if required, see more details below.
  • 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, see more details below.
  • You wanna retrieve the file that the user selected, rewrite get_file() if required, see more details below.
  • Optional question that you should ask yourself is 'Does the user can execute a search', if they do, you will have to rewrite search() method, see more details below.

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'=>'1340002147', 'size'=>'10451213', 'source'=>'http://www.moodle.com/dl.rar'),
   array('title'=>'folder', 'date'=>'1340002147', 'size'=>'0', 'children'=>array())

) ); The full specification of list element:

array(
  // 'path' is 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 clicks the folder, it will send a ajax request to server side.
  // Default value is false but note that non-Javascript file picker always acts as if dynload was set to true
  'dynload' => (bool) use dynamic loading,
  // if you are using pagination, 'page' and 'pages' parameters should be set.
  // It is not recommended to use pagination and subfolders at the same time, the tree view mode can not handle it correctly
  'page' => (int) which page is this list
  'pages' => (int) how many pages. If number of pages is unknown but we know that the next page exists repository may return -1
  'manage' => (string) url to file manager for the external repository, if specified will display link in file picker
  'help' => (string) url to the help window, if specified will display link in file picker
  'nologin' => (bool) requires login, default false, if set to true the login link will be removed from file picker
  'norefresh' => (bool) no refresh button, default false
  'logouttext' => (string) in case of nologin=false can substitute the text 'Logout' for logout link in file picker
  'nosearch' => (bool) no search link, default false, if set to true the search link will be removed from file picker
  'issearchresult' => (bool) tells that this listing is the result of search
  // for repositories that actually upload a file: set 'upload' option to display an upload form in file picker
  'upload' => array( // upload manager
    'label' => (string) label of the form element,
    'id' => (string) id of the form element
  ),
  // 'list' is used by file picker to build a file/folder tree
  'list' => array(
    array( // file
      'title' => (string) file name,
      'shorttitle' => (string) optional, if you prefer to display a short title
      'date' => (int) UNIX timestamp, default value for datemodified and datecreated,
      'datemodified' => (int) UNIX timestamp when the file was last modified [2.3+],
      'datecreated' => (int) UNIX timestamp when the file was last created [2.3+],
      'size' => (int) file size in bytes,
      'thumbnail' => (string) url to thumbnail for the file,
      'thumbnail_width' => (int) the width of the thumbnail image,
      'thumbnail_height' => (int) the height of the thumbnail image,
      'source' => plugin-dependent unique path to the file (id, url, path, etc.),
      'url' => the accessible url of file,
      'icon' => (string) url to icon of the image (24x24px), if omitted the moodle filetype icon will be used [2.3+],
      'realthumbnail' => (string) url to image preview to be lazy-loaded when scrolled to it (if it requires to be generated and can not be returned as 'thumbnail') [2.3+],
      'realicon' => (string) url to image preview in icon size (24x24) [2.3+],
      'author' => (string) default value for file author,
      'license' => (string) default value for license (short name, see class license_manager),
      'image_height' => (int) if the file is an image, image height in pixels, null otherwise [2.3+],
      'image_width' =>  (int) if the file is an image, image width in pixels, null otherwise [2.3+]
    ),
    array( // folder - similar to file, has also 'path' and 'children' but no 'source' or 'url'
      'title' => (string) folder name,
      'shorttitle' => (string) optional, if you prefer to display a short title
      'path' => (string) path to this folder. In case of dynload=true (and for non-JS filepicker) the value will be passed to repository_xxx::get_listing() in order to retrieve children
      'date', 'datemodified', 'datecreated', 'thumbnail', 'icon' => see above,
      'children' => array( 
        // presence of this attribute actually tells file picker that this is a folder. In case of dynload=true, it should be empty array
        // otherwise it is a nested list of contained 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 only instead of building the whole file tree.

Example of dynamically loading See Alfresco plug-in

Functions you can override

get_file_source_info (2.3+)

Returns the value to be stored in files.source field in DB (regardless whether file is picked as a copy or by reference). It indicates where the file came from. It is advised to include either full URL here or indication of the repository. Examples: 'Dropbox: /filename.jpg', 'http://fullurl.com/path/file', etc. This value will be used to display warning message if reference can not be restored from backup. Also it can (although not has to) be used in get_reference_details() to produce the human-readable reference source in the fileinfo dialogue in the file manager.

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 = new stdClass();
           $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 = new stdClass();
           $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.

A custom search form must include the following:

  • A hidden element named repo_id and the value must be the id of the repository instance
  • A hidden element named ctx_id and the value must be the context id of the repository instance
  • A hidden element named sesskey and the value must be the session key
  • A text field element named s, this is where users will type in their search criteria

class repository_myrepo extends repository {

   // other required functions
   ....
   public function search($search_text, $page = 0) { // Since Moodle 2.3, the page argument is required
       // Hidden field repo instance id
       $attributes = array('type'=>'hidden',
                           'name' => 'repo_id',
                           'value' => $this->id);
       $html .= html_writer::empty_tag('input', $attributes);
       // hidden field context id
       $attributes['name'] = 'ctx_id';
       $attributes['value'] = $this->context->id;
       $html .= html_writer::empty_tag('input', $attributes);
       // hidden field session key
       $attributes['name'] = 'sesskey';
       $attributes['value'] = sesskey();
       $html .= html_writer::empty_tag('input', $attributes);
       // label search name
       $param = array('for' => 'label_search_name');
       $title = get_string('search_name', 'myrepo_search_name');
       $html .= html_writer::tag('label', $title, $param);
       $html .= html_writer::empty_tag('br');
       // text field search name
       $attributes['type'] = 'text';
       $attributes['name'] = 's';
       $attributes['value'] = ;
       $attributes['title'] = $title;
       $html .= html_writer::empty_tag('input', $attributes);
       $html .= html_writer::empty_tag('br');
       
       return $html;
   }

}

search

This function will do the searching job. You can obtain the POST parameters from the forum 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.

Repository support for returning file as alias/shortcut

From Moodle 2.3 it became possible to link to the file from external (or internal) repository by reference. In UI it is called “create alias/shortcut”. This creates a row in {files} table but the contents of the file is not stored. Although it may be cached by repository if developer wants to.

Make sure that function supported_returntypes() returns FILE_REFERENCE among other types.

Note that external file is synchronised by moodle when UI wants to show the file size.

get_reference_details

When file in moodle filearea is a reference to file in some repository, filemanager can display the location of the original. This function is responsible for returning human-readable location. It is usually prefixed with repository name and semicolon.

get_reference_file_lifetime

how often to synchronise the file

sync_individual_file

Decide whether or not the file should be synced (by default true). This is checked after the lifetime is checked.

get_file_by_reference

This is actual synchronisation performed when sync conditions are met. Note that it is not necessary to download file here. This is just needed to find out if filesize and/or contenthash have changed since the last synchronization. This function returns null if source file can not be found any more. Otherwise it returns an object with file information (see phpdocs). The preferable output is only contenthash/filesize: if repository is able to retrieve this information without downloading file into moodle it is the best. Don’t forget that this function might be called quite often since filemanager always wants to know the file size.

send_file

Repository method to serve the referenced file. This function is called when user actually tries to download/view the file. But it still can return the cached copy if repository developer wishes so.

I18n - Internationalization

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

$string['pluginname'] = 'Flickr Public'; $string['configplugin'] = 'Flickr Public configuration'; $string['pluginname_help'] = 'A Flickr public repository';

Database Tables

repository

Field Type Default Info
id int(10) autoincrementing
type varchar(255) The type of the repository
visible tinyint(1)
sortorder int(10)

repository_instances

This table contains one entry for every configured external repository instance.

Field Type Default Info
id int(10) autoincrementing
name varchar 255 A custom name for this repository (non-unique)
typeid int(10) The id of repository type
userid int(10) The person who created this repository instance
contextid int(10) The context that this repository is available to ( = system context for site-wide ones)
username varchar(255) username to log in with, if required (almost never!)
password varchar(255) password to log in with, if required (almost never!)
timecreated int(10) The time this repository was created
timemodified int(10) The last time the repository was modified

repository_instance_config

Field Type Default Info
id int(10) autoincrementing
instanceid int(int)
name varchar(255)
value Text


See also