MoodleDocs - User contributions [en]

Course module

2013-09-26T14:21:13Z

Davosmith: /* Database tables */

==Summary==
A course module (often abbreviated 'cm') represents each of the activities and resources found in a course. It contains information about which course and section the activity / resource is displayed on, as well as details about the visibility, group and completion status of the activity.

==Database tables==
The data for the course module is stored in the database table 'mdl_course_modules' (the 'mdl_' part will be different if you have chosen a non-default prefix for your database tables). The fields in this table link it to a number of other tables in the database.
* The 'course' field links to the 'mdl_course' table, which contains everything you need to know about a course.
* The 'module' table links to the 'mdl_modules' table, which gives information about the type of the module (e.g. 'quiz', 'resource') as well as its current version number.
* After looking up the type of the module, the rest of the details about this module can be found by looking up the 'instance' value (from the 'mdl_course_modules' table) in the 'mdl_{type}' table. Here you can find the name and introductory paragraph for the activity / resource, as well as information that is specific to the type of activity being looked at.

You can quickly gather all of this information, by using the 'get_fast_modinfo($course)' function. The easiest way to understand the data returned is to use the following code:
<code php>
global $DB;
$course = $DB->get_record('course', array('id' => $courseid));
$info = get_fast_modinfo($course);
print_object($info);
</code>

==Usage==
The cmid (course module id) is used widely throughout Moodle to identify a specific activity / resource. Some of the most important uses are:
* When linking to a modules 'view.php' script, it is passed as the 'id' parameter
* To get the 'context' for the module (used when checking user capabilities or linking files to an activity), via the function call 'context_module::instance($cmid)' (before Moodle 2.2 this was 'get_context_instance(CONTEXT_MODULE, $cmid)')
* Every log entry in 'mdl_log' that relates to a specific activity has the 'cmid' field set

==More documentation==
* [[Module visibility and display]]
* [http://phpdocs.moodle.org/HEAD/core/lib/course_modinfo.html course_modinfo PHPdocs]
* [http://phpdocs.moodle.org/HEAD/core/lib/cm_info.html cminfo PHPdocs]

File API

2013-08-05T07:25:12Z

Davosmith: /* Serving files to users */ Add an example of the MYPLUGIN_pluginfile function

{{Moodle 2.0}}
==Overview==

The File API is for managing all the files stored by Moodle. If you are interested in how the file API works internally, see [[File API internals]]. The page is just about what you need to know to use the file API. Related is the [[Repository API]], which lets users get files into Moodle.

If you are looking for an explanation on how to manage moodle files in moodle forms, you most likely need to read [[Using_the_File_API_in_Moodle_forms|Using the File API in Moodle forms]].

==File areas==

Files are conceptually stored in '''file areas'''. A file area is uniquely identified by:
* A context id.
* full component name (using [[Frankenstyle]]), for example 'course', 'mod_forum', 'mod_glossary', 'block_html'.
* A file area type, for example 'intro' or 'post'.
* A unique itemid. Normally, the itemid relates to something depending on the file area type. For example, for a 'course', 'intro' file area, the itemid is 0. For forum post, it is the post id.

File areas are not listed separately anywhere, they are stored implicitly in the files table. Please note that each subsystem is allowed to access only own file areas, for example only code in /mod/assignment/* may access files with component 'mod_assignment'.

===Naming file areas===

The names of the file areas are not strictly defined, but it is strongly recommended to use singulars and common names of areas if possible (intro, post, attachment, description, ...).

==Serving files to users==

You must refer to the file with a URL that includes a file-serving script, often pluginfile.php. For example

The general form of the URL is something like
<code php>
$url = $CFG->wwwroot/pluginfile.php/$contextid/$component/$filearea/arbitrary/extra/infomation.ext
</code>

A specific example might be
<code php>
$url = $CFG->wwwroot/pluginfile.php/$forumcontextid/mod_forum/post/$postid/image.jpg
</code>

Usually, you do not need to construct this URL directly - the function moodle_url::make_pluginfile_url() should be used instead:
<code php>
$url = moodle_url::make_pluginfile_url($file->get_contextid(), $file->get_component(), $file->get_filearea(), $file->get_itemid(), $file->get_filepath(), $file->get_filename());
</code>
Note: If you do not need the 'itemid', then pass null in as this parameter and it will be entirely missed out from the URL - you need to take this into account when serving the file in the callback function, below.

The file serving script then looks at the context id, and component name, and the file area name, and based on that arranges for the file to be served, following appropriate security checks.

<strong>Note: </strong>In most cases, when developing third party plugins, pluginfile.php looks for a '''callback function''' in the appropriate plugin. These functions are stored in '''lib.php''' files and are named '''component_name_pluginfile()'''. The arbitrary/extra/infomation.ext is passed to the callback. For example, files in the mod_forum+post file area end up being served by the mod_forum_pluginfile function in mod/forum/lib.php. This function in MYPLUGIN/lib.php will usually follow a pattern like the example below, but the details will vary depending on the restrictions your plugin places on accessing different files (e.g. assignment files can only be accessed by teachers and the student who submitted the file, forum attachments require access to the discussion they are posted on):
<code php>
function MYPLUGIN_pluginfile($course, $cm, $context, $filearea, $args, $forcedownload, array $options=array()) {
// Check the contextlevel is as expected - if your plugin is a block, this becomes CONTEXT_BLOCK, etc.
if ($context->contextlevel != CONTEXT_MODULE) {
return false;
}

// Make sure the filearea is one of those used by the plugin.
if ($filearea !== 'expectedfilearea' && $filearea !== 'anotherexpectedfilearea') {
return false;
}

// Make sure the user is logged in and has access to the module (plugins that are not course modules should leave out the 'cm' part).
require_login($course, true, $cm);

// Check the relevant capabilities - these may vary depending on the filearea being accessed.
if (!has_capability('mod/MYPLUGIN:view', $context)) {
return false;
}

// Leave this line out if you set the itemid to null in make_pluginfile_url (set $itemid to 0 instead).
$itemid = array_shift($args); // The first item in the $args array.

// Use the itemid to retrieve any relevant data records and perform any security checks to see if the
// user really does have access to the file in question.

// Extract the filename / filepath from the $args array.
$filename = array_pop($args); // The last item in the $args array.
if (!$args) {
$filepath = '/'; // $args is empty => the path is '/'
} else {
$filepath = '/'.implode('/', $args).'/'; // $args contains elements of the filepath
}

// Retrieve the file from the Files API.
$fs = get_file_storage();
$file = $fs->get_file($context->id, 'mod_MYPLUGIN', $filearea, $itemid, $filepath, $filename);
if (!$file) {
return false; // The file does not exist.
}

// We can now send the file back to the browser - in this case with a cache lifetime of 1 day and no filtering.
send_file($file, 86400, 0, $forcedownload, $options);
}
</code>

You normally use an API function to generate these URL automatically, most often the <tt>file_rewrite_pluginfile_urls</tt> function.

==Getting files from the user==

* See [[Using_the_File_API_in_Moodle_forms|Using the File API in Moodle forms]]

==Examples==
Please note that in reality developers outside of core will not deal with file api directly in majority of cases, instead use formslib elements which are doing all this automatically.

===Browsing files===
<code php>
$browser = get_file_browser();
$context = get_system_context();

$filearea = null;
$itemid = null;
$filename = null;
if ($fileinfo = $browser->get_file_info($context, $component, $filearea, $itemid, '/', $filename)) {
// build a Breadcrumb trail
$level = $fileinfo->get_parent();
while ($level) {
$path[] = array('name'=>$level->get_visible_name());
$level = $level->get_parent();
}
$path = array_reverse($path);
$children = $fileinfo->get_children();
foreach ($children as $child) {
if ($child->is_directory()) {
echo $child->get_visible_name();
// display contextid, itemid, component, filepath and filename
var_dump($child->get_params());
}
}
}

</code>

===Moving files around===

For example, if you have just built a file at the path
<code php>
$from_zip_file = $CFG->dataroot . '/temp/backup/' . $preferences->backup_unique_code .
'/' . $preferences->backup_name;
</code>
And you want to move it into the course_backup file area, do
<code php>
$context = get_context_instance(CONTEXT_COURSE, $preferences->backup_course);
$fs = get_file_storage();
$file_record = array('contextid'=>$context->id, 'component'=>'course', 'filearea'=>'backup',
'itemid'=>0, 'filepath'=>'/', 'filename'=>$preferences->backup_name,
'timecreated'=>time(), 'timemodified'=>time());
$fs->create_file_from_pathname($file_record, $from_zip_file);
</code>

=== List area files ===
<code php>
$fs = get_file_storage();
$files = $fs->get_area_files($contextid, 'mod_assignment', 'submission', $submission->id);
foreach ($files as $f) {
// $f is an instance of stored_file
echo $f->get_filename();
}
</code>

Or as links...

<code php>
$out = array();

$fs = get_file_storage();
$files = $fs->get_area_files($contextid, 'mod_assignment', 'submission', $submission->id);

foreach ($files as $file) {
$filename = $file->get_filename();
$url = moodle_url::make_file_url('/pluginfile.php', array($file->get_contextid(), 'mod_assignment', 'submission',
$file->get_itemid(), $file->get_filepath(), $filename));
$out[] = html_writer::link($url, $filename);
}
$br = html_writer::empty_tag('br');

return implode($br, $out);
</code>

=== Create file ===

Here's how to create a file whose contents will be a text string. This is the equivalent of the PHP function <tt>file_put_contents</tt>.

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
'contextid' => $context->id, // ID of context
'component' => 'mod_mymodule', // usually = table name
'filearea' => 'myarea', // usually = table name
'itemid' => 0, // usually = ID of row in table
'filepath' => '/', // any path beginning and ending in /
'filename' => 'myfile.txt'); // any filename

// Create file containing text 'hello world'
$fs->create_file_from_string($fileinfo, 'hello world');
</code>

If you want to create a file in the Moodle file area based on a 'real' file e.g. in a temporary folder, you can use <tt>create_file_from_pathname</tt> instead. Similarly, you can create a file based on some other file already in Moodle's local files by using <tt>create_file_from_storedfile</tt>. Browse through <tt>lib/filestorage/file_storage.php</tt> for details.

Unlike with ordinary files, this method will not automatically overwrite an existing file. If you wish to overwrite a file, you must first get the file and (if it exists) delete it, and only then create it again.

=== Read file ===

This is a way to read a file, equivalent to <tt>file_get_contents</tt>. '''Please note your are allowed to do this ONLY from mod/mymodule/* code, it is not acceptable to do this anywhere else.''' Other code has to use file_browser interface instead.

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
'component' => 'mod_mymodule', // usually = table name
'filearea' => 'myarea', // usually = table name
'itemid' => 0, // usually = ID of row in table
'contextid' => $context->id, // ID of context
'filepath' => '/', // any path beginning and ending in /
'filename' => 'myfile.txt'); // any filename

// Get file
$file = $fs->get_file($fileinfo['contextid'], $fileinfo['component'], $fileinfo['filearea'],
$fileinfo['itemid'], $fileinfo['filepath'], $fileinfo['filename']);

// Read contents
if ($file) {
$contents = $file->get_content();
} else {
// file doesn't exist - do something
}
</code>

If you want to access the file directly on disk, this is not permitted. Instead, you need to make a copy of the file in a temporary area and use that. You can do this with <tt>$file->copy_content_to($pathname)</tt>.

=== Delete file ===

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
'component' => 'mod_mymodule',
'filearea' => 'myarea', // usually = table name
'itemid' => 0, // usually = ID of row in table
'contextid' => $context->id, // ID of context
'filepath' => '/', // any path beginning and ending in /
'filename' => 'myfile.txt'); // any filename

// Get file
$file = $fs->get_file($fileinfo['contextid'], $fileinfo['component'], $fileinfo['filearea'],
$fileinfo['itemid'], $fileinfo['filepath'], $fileinfo['filename']);

// Delete it if it exists
if ($file) {
$file->delete();
}
</code>

==See also==

* [[Core APIs]]
* [[File API internals]] how the File API works internally.
* [[Using the File API in Moodle forms]]

[[Category:Files]]
[[Category:API]]

Setting up xhprof on Moodle

2013-02-18T09:37:32Z

Davosmith: /* Installing xhprof */

The following instructions are for setting up xhprof for Moodle under a Ubuntu/Debian environment. The process should be similar for other linux enviroments, but will need some tweaking if you wish to do this under windows. Please update this document if you find any major problems.

==Installing xhprof==

<code bash>
mkdir ~/src/
cd ~/src/
wget http://pecl.php.net/get/xhprof-0.9.2.tgz
tar xvf xhprof-0.9.2.tgz
cd xhprof-0.9.2/extension/
phpize
./configure
make
sudo make install
</code>

Note: The version downloaded via these instructions is not compatible with PHP 5.4 - instead you should download the latest version of the code from https://github.com/facebook/xhprof (before following the instructions from 'cd xhprof-0.9.2/extension/' onwards).

Add the following to the apache version of you php.ini file

<code ini>
[xhprof]
extension=xhprof.so
xhprof.output_dir="/var/tmp/xhprof"
</code>

Restart Apache
<code bash>
sudo service apache2 restart
</code>

Create a file in your web root that makes a call to phpinfo(); and then view the result in your browser to make sure that xhprof is enabled in PHP. Checking the output of '''php -m''' would also work if you are sure that the command line version of PHP uses the same php.ini file as your web server.

==Configuring Moodle to use xhprof==
[[Image:profilingOption.png|thumb|left|The profiling option is displayed when the php xhprof extension is installed]]
[[Image:profilingOutput.png|thumb|right|Tabular profiling output produced by xhprof]]
[[Image:callgraph.png|thumb|right|An example call graph showing slow parts of the profiled run]]
Once the xhprof php extension is correctly installed you will find a new "Profiling" option available under Settings > Site administration > Development

When you load the profiling settings page you are confronted with several options. In order to get xhprof up and running with minimal fuss you mearly need to check the "Enable profiling" box and set a path that you wish to be profiled. You can simply set this to a wildcard using the asterisk symbol ('''*''') while you are testing profiling. Afterwards you can come back and set this to a more restrictive setting once you know profiling is working. Note the paths need to be specified relative to your Moodle directory and not the web root.

After you have enabled profiling you should load some pages within the "Profile these" filter that you set in the step above. Once you have done these go to Settings > Site administration > Development > Profiling runs and you should see a list of the pages you visited. Clicking on one of these and then clicking on the "View profiling details" will take you to a profiling table full of helpful stats for tracking down slow pages and functions. You can get an even more ineresting breakdown of this by then clicking on the "View Full Callgraph" link. This callgraph makes it easy to see where the slow parts of each particular run are and functions which individually may not take a long time to run but which are run thousands of times and thus resulting in a great deal of slowdown.
[[Image:profilingSettings.png|frame|center|Enabling profiling and setting it to run on all pages via a wildcard]]
[[Image:profilingRuns.png|frame|left|A profiling runs option can be seen after enabling profiling]]

version.php

2013-01-23T13:48:27Z

Davosmith: Fixed Moodle 2.2 version number

This file is included in the main directory of plugin. It is compulsory for most plugin types. Even when not compulsory it is highly recommended.

It contains a number of fields, which are used during the install / upgrade process to make sure the plugin is compatible with the current Moodle install, as well as spotting whether an upgrade is needed.

The file is a standard PHP file, starting with an opening '<?php' tag and defining the following variables:

'''Note! For Activity modules replace $plugin-> with $module-> in the following example!'''

* $plugin->version = 2011051000;
** Required - the version number of your plugin in the form YYYYMMDDxx, so this example is 10th May 2011 (with 00 indicating this is the first version for that day)
* $plugin->requires = 2010112400;
** Optional - minimum version number of Moodle that this plugin requires (Moodle 1.9 = 2007101509; Moodle 2.0 = 2010112400; Moodle 2.1 = 2011070100; Moodle 2.2 = 2011120500; Moodle 2.3 = 2012062500). See [[Releases]] for a full list.
* $plugin->cron = 0;
** Optional - time interval (in seconds) between calls to the plugin's 'cron' function; set to 0 to disable the cron function calls.
** Cron support is not yet implemented for all plugins.
* $plugin->component = 'plugintype_pluginname';
** Optional - ''frankenstyle'' plugin name, strongly recommended. It is used for installation and upgrade diagnostics.
* $plugin->maturity = MATURITY_STABLE;
** Optional - how stable the plugin is: MATURITY_ALPHA, MATURITY_BETA, MATURITY_RC, MATURITY_STABLE (Moodle 2.0 and above)
* $plugin->release = '2.x (Build: 2011051000)';
** Optional - Human-readable version name
* $plugin->dependencies = array('mod_forum' => ANY_VERSION, 'mod_data' => 2010020300);
** Optional - list of other plugins that are required for this plugin to work (Moodle 2.2 and above)
** In this example, the plugin requires any version of the forum activity and version '20100020300' (or above) of the database activity

Here is a template to copy and paste:
<code php>
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* TODO
*
* @package TODO_FRANKENSTYLE
* @copyright TODO
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

defined('MOODLE_INTERNAL') || die();

$plugin->version = TODO;
$plugin->requires = TODO; // See https://docs.moodle.org/dev/Moodle_Versions
$plugin->cron = 0;
$plugin->component = 'TODO_FRANKENSTYLE';
$plugin->maturity = MATURITY_STABLE;
$plugin->release = 'TODO';

$plugin->dependencies = array(
'mod_forum' => ANY_VERSION,
'mod_data' => TODO
);
</code>

==See also==

* [[Moodle versions]]

[[Category:Plugins]]

Repository plugins

2013-01-21T16:34:34Z

Davosmith: Fix typo

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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. [[lib/formslib.php Form Definition]] has details of all the types of elements you can add to the settings form.

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

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'src' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===User login (optional)===
If the plugin requires login from the user at the time when they use it, then these functions can be used.

====print_login====
Returns an array of the elements required in the login form. If no login form is required, then the default implementation of this will redirect to the files list. If $this->options['ajax'] is not set, then an HTML-snippet with the login fields (but not the form tags) should be output, instead of returning the form details.
<code php>
public function print_login() { // From repository_alfresco
if ($this->options['ajax']) {
$user_field = new stdClass();
$user_field->label = get_string('username', 'repository_alfresco').': ';
$user_field->id = 'alfresco_username';
$user_field->type = 'text';
$user_field->name = 'al_username';

$passwd_field = new stdClass();
$passwd_field->label = get_string('password', 'repository_alfresco').': ';
$passwd_field->id = 'alfresco_password';
$passwd_field->type = 'password';
$passwd_field->name = 'al_password';

$ret = array();
$ret['login'] = array($user_field, $passwd_field);
return $ret;
} else { // Non-AJAX login form - directly output the form elements
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_alfresco').'</label></td>';
echo '<td><input type="text" name="al_username" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_alfresco').'</label></td>';
echo '<td><input type="password" name="al_password" /></td></tr>';
echo '</table>';
echo '<input type="submit" value="Enter" />';
}
}
</code>
This will help to generate a form by file picker which contains user name and password input elements.

For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the '__construct' function, via $submitted = optional_param('fieldname', [defaultvalue], PARAM_INT/PARAM_TEXT).
<code php>
public function __construct($repositoryid, $context = SYSCONTEXTID, $options = array()) {
// Taken from repository_alfresco

/* Skipping code that is not relevant to user login */

$this->alfresco = new Alfresco_Repository($this->options['alfresco_url']);
$this->username = optional_param('al_username', '', PARAM_RAW);
$this->password = optional_param('al_password', '', PARAM_RAW);
try{
// deal with user logging in
if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {
$this->ticket = $this->alfresco->authenticate($this->username, $this->password);
$SESSION->{$this->sessname} = $this->ticket;
} else {
if (!empty($SESSION->{$this->sessname})) {
$this->ticket = $SESSION->{$this->sessname};
}
}
$this->user_session = $this->alfresco->createSession($this->ticket);
$this->store = new SpacesStore($this->user_session);
} catch (Exception $e) {
$this->logout();
}
$this->current_node = null;

/* Skipping code that is not relevant to user login */

}
</code>

Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.
<code php>
public function print_login(){ // Code taken from repository_boxnet
$t = $this->boxclient->getTicket();
if ($this->options['ajax']) {
$popup_btn = new stdClass();
$popup_btn->type = 'popup';
$popup_btn->url = ' https://www.box.com/api/1.0/auth/' . $t['ticket'];

$ret = array();
$ret['login'] = array($popup_btn);
return $ret;
} else {
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_boxnet').'</label></td>';
echo '<td><input type="text" name="boxusername" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_boxnet').'</label></td>';
echo '<td><input type="password" name="boxpassword" /></td></tr>';
echo '<input type="hidden" name="ticket" value="'.$t['ticket'].'" />';
echo '</table>';
echo '<input type="submit" value="'.get_string('enter', 'repository').'" />';
}
}
</code>

====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.
<code php>
public function check_login() { // Taken from repository_alfresco
global $SESSION;
return !empty($SESSION->{$this->sessname});
}
</code>
====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. After this the code should return something suitable to display to the user (usually the results of calling $this->print_login() ):
<code php>
public function logout() { // Taken from repository_alfresco
global $SESSION;
unset($SESSION->{$this->sessname});
return $this->print_login();
}
</code>

===Transferring files to Moodle (optional)===
These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.

====get_file_reference($source)====
Rarely does anything other than return the $source param (the default action if not overridden), but takes the 'source' reference from the browser (originally specified in the list returned by 'get_listing') and makes sure it is ready to be passed on to the 'get_file' or 'get_file_by_reference' functions (below).

====get_file($url, $filename = "")====
For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:
* path - the local path where the file was saved
* url - the $url param passed into the function

<code php>
public function get_file($url, $filename = '') {
// Default implementation from the base 'repository' class
$path = $this->prepare_file($filename); // Generate a unique temporary filename
$c = new curl;
$result = $c->download_one($url, null, array('filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT));
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>
<code php>
public function get_file($reference, $filename = '') {
// Slightly extended version taken from repository_equella
global $USER;
// Extract the details saved in the 'source' param by
// repository/equella/callback.php (now in the $reference paramater)
$ref = @unserialize(base64_decode($reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}
$path = $this->prepare_file($filename);
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie'=>$cookiepathname));
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT));
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>

====get_link($url)====
Used with FILE_EXTERNAL to convert a reference (from 'get_file_reference', but ultimately from the output of 'get_listing') into a URL that can be used directly by the end-user's browser. Usually just returns the original $url, but may need further transformation based on the internal implementation of the repository plugin.

{{Moodle 2.3}}====get_file_source_info($source)====
Takes the 'source' field from 'get_listing' (as returned by the user's browser) and 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.

===Search functions (optional)===

These functions allow you to implement search functionality within your repository.

====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 text field element named '''s''', this is where users will type in their search criteria

The following fields are automatically inserted in Moodle 2.3+ (but may need to be manually included in earlier versions):
* 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

<code php>
public function print_search() {
// The default implementation in class 'repository'
global $PAGE;
$renderer = $PAGE->get_renderer('core', 'files');
return $renderer->repository_default_searchform();
}

// From core_files_renderer (repository/renderer.php)
public function repository_default_searchform() {
$str = '<div class="fp-def-search"><input name="s" value='.get_string('search', 'repository').' /></div>';
return $str;
}
</code>

<code php>
public function print_search() {

// 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;
}
</code>

====search($search_text, $page = 0)====
Return the results of doing the search. Any additional parameters from the search form can be retrieved by $param = optional_param('paramname', [defaultvalue], PARAM_INT / PARAM_TEXT);. The return should return an array containing:
* list - with the same layout as the 'list' element in 'get_listing'
<code php>
public function search($search_text, $page = 0) {
// Example from repoistory_googledocs
$gdocs = new google_docs($this->googleoauth);

$ret = array();
$ret['dynload'] = true;
$ret['list'] = $gdocs->get_file_list($search_text);
return $ret;
}
</code>

====global_search()====
Return true if should be included in a search throughout all repositories (currently not available via the UI)

{{Moodle 2.3}}===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_file_lifetime()====
Return minimum number of seconds before checking for changes to the file (default implementation = 1 day)
<code php>
public function get_reference_file_lifetime($ref) {
return 60 * 60 * 24; // One day
}
</code>

====sync_individual_file(stored_file $storedfile)====
Called after the file has reached the 'lifetime' specified above to see if it should now be synchronised (default implementation is to return true)
<code php>
public function sync_individual_file(stored_file $storedfile) {
return true;
}
</code>

====get_reference_details($reference, $filestatus = 0)====
Returns human-readable information about where the original file is stored (to be displayed in the filepicker properties box). It is usually prefixed with repository name and semicolon (e.g. 'Myrepository: http://url.to.file'). $reference is the 'source' output by 'get_listing'. $filestatus can be either 0 (OK - default) or 666 (source file missing).
<code php>
public function get_reference_details($reference, $filestatus = 0) {
// Example taken from repository_equella
if (!$filestatus) {
$ref = unserialize(base64_decode($reference));
return $this->get_name(). ': '. $ref->filename;
} else {
return get_string('lostsource', 'repository', '');
}
}
</code>

====get_file_by_reference($reference)====
Returns up-to-date information about the original file, only called when the 'lifetime' is reached and 'sync_individual_file' returns true.
* for image files - download the file and return either $ret->filepath (full path on the server), $ret->handle (open handle to the file) or $ret->content (raw data from the file) to allow the file to be saved into the Moodle filesystem and the thumbnail to be updated
* for non-image files - avoid downloading the file (if possible) and just return $ret->filesize to update that information
* for missing / inaccessible files - return null
Remember this function may be called quite a lot, as the filemanager often wants to know the filesize.
<code php>
public function get_file_by_reference($reference) {
// Example taken from repository_equella
global $USER;
// Extract the remote file identifier
$ref = @unserialize(base64_decode($reference->reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}

// Download the file details
$return = null;
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie' => $cookiepathname));
if (file_extension_in_typegroup($ref->filename, 'web_image')) {
// The file is an image - download and return the file path
$path = $this->prepare_file('');
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::SYNCIMAGE_TIMEOUT));
if ($result === true) {
$return = (object)array('filepath' => $path);
}
} else {
// The file is not an image - just get the file details
$result = $c->head($url, array('followlocation' => true, 'timeout' => self::SYNCFILE_TIMEOUT));
}
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}

$this->connection_result($c->get_errno());
$curlinfo = $c->get_info();
if ($return === null && isset($curlinfo['http_code']) && $curlinfo['http_code'] == 200
&& array_key_exists('download_content_length', $curlinfo)
&& $curlinfo['download_content_length'] >= 0) {
// we received a correct header and at least can tell the file size
$return = (object)array('filesize' => $curlinfo['download_content_length']);
}
return $return;
}
</code>

====send_file($storedfile, $lifetime=86400, $filter=0, $forcedownload=false, array $options = null)====
Send the requested file back to the user's browser. The 'reference' for the file can be found via $storedfile->get_reference(). If the file is not found / no longer exists, the function 'send_file_not_found()' should be used. Otherwise the file should be output directly, via the most appropriate method - e.g. use a 'Location: ' header to redirect to the external URL; or download the file and cache within the Moodle filesystem (possibly using '$this->import_external_file_contents()'), then call 'send_stored_file'. Note, it is up to the repository developer to decide whether to actually download the file or to return a locally cached copy instead.
<code php>
public function send_file($stored_file, $lifetime=86400 , $filter=0, $forcedownload=false, array $options = null) {
// Example taken from repository_equella
$reference = unserialize(base64_decode($stored_file->get_reference()));
$url = $this->appendtoken($reference->url);
if ($url) {
header('Location: ' . $url);
} else {
send_file_not_found();
}
}
</code>
An example of caching files within the Moodle filesystem can be found in repository_dropbox.

===Misc functions===

A couple of other useful functions to be aware of.

====get_name()====
Returns the human-readable name for this instance of the plugin (the default implementation should usually be fine and this function can be useful when doing any output to the user).

====cron()====
For any background tasks that need to be scheduled (rarely needed). The minimum time between calls is specified in the version.php file (but the maximum time depends on the server settings for the Moodle install).

== I18n - Internationalization ==
These following strings are required in ''moodle/repository/myplugin/lang/en/repository_myplugin.php'' or ''moodle/lang/en/repository_myplugin.php'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-06T18:31:54Z

Davosmith: /* Template */

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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. [[lib/formslib.php Form Definition]] has details of all the types of elements you can add to the settings form.

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

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===User login (optional)===
If the plugin requires login from the user at the time when they use it, then these functions can be used.

====print_login====
Returns an array of the elements required in the login form. If no login form is required, then the default implementation of this will redirect to the files list. If $this->options['ajax'] is not set, then an HTML-snippet with the login fields (but not the form tags) should be output, instead of returning the form details.
<code php>
public function print_login() { // From repository_alfresco
if ($this->options['ajax']) {
$user_field = new stdClass();
$user_field->label = get_string('username', 'repository_alfresco').': ';
$user_field->id = 'alfresco_username';
$user_field->type = 'text';
$user_field->name = 'al_username';

$passwd_field = new stdClass();
$passwd_field->label = get_string('password', 'repository_alfresco').': ';
$passwd_field->id = 'alfresco_password';
$passwd_field->type = 'password';
$passwd_field->name = 'al_password';

$ret = array();
$ret['login'] = array($user_field, $passwd_field);
return $ret;
} else { // Non-AJAX login form - directly output the form elements
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_alfresco').'</label></td>';
echo '<td><input type="text" name="al_username" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_alfresco').'</label></td>';
echo '<td><input type="password" name="al_password" /></td></tr>';
echo '</table>';
echo '<input type="submit" value="Enter" />';
}
}
</code>
This will help to generate a form by file picker which contains user name and password input elements.

For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the '__construct' function, via $submitted = optional_param('fieldname', [defaultvalue], PARAM_INT/PARAM_TEXT).
<code php>
public function __construct($repositoryid, $context = SYSCONTEXTID, $options = array()) {
// Taken from repository_alfresco

/* Skipping code that is not relevant to user login */

$this->alfresco = new Alfresco_Repository($this->options['alfresco_url']);
$this->username = optional_param('al_username', '', PARAM_RAW);
$this->password = optional_param('al_password', '', PARAM_RAW);
try{
// deal with user logging in
if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {
$this->ticket = $this->alfresco->authenticate($this->username, $this->password);
$SESSION->{$this->sessname} = $this->ticket;
} else {
if (!empty($SESSION->{$this->sessname})) {
$this->ticket = $SESSION->{$this->sessname};
}
}
$this->user_session = $this->alfresco->createSession($this->ticket);
$this->store = new SpacesStore($this->user_session);
} catch (Exception $e) {
$this->logout();
}
$this->current_node = null;

/* Skipping code that is not relevant to user login */

}
</code>

Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.
<code php>
public function print_login(){ // Code taken from repository_boxnet
$t = $this->boxclient->getTicket();
if ($this->options['ajax']) {
$popup_btn = new stdClass();
$popup_btn->type = 'popup';
$popup_btn->url = ' https://www.box.com/api/1.0/auth/' . $t['ticket'];

$ret = array();
$ret['login'] = array($popup_btn);
return $ret;
} else {
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_boxnet').'</label></td>';
echo '<td><input type="text" name="boxusername" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_boxnet').'</label></td>';
echo '<td><input type="password" name="boxpassword" /></td></tr>';
echo '<input type="hidden" name="ticket" value="'.$t['ticket'].'" />';
echo '</table>';
echo '<input type="submit" value="'.get_string('enter', 'repository').'" />';
}
}
</code>

====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.
<code php>
public function check_login() { // Taken from repository_alfresco
global $SESSION;
return !empty($SESSION->{$this->sessname});
}
</code>
====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. After this the code should return something suitable to display to the user (usually the results of calling $this->print_login() ):
<code php>
public function logout() { // Taken from repository_alfresco
global $SESSION;
unset($SESSION->{$this->sessname});
return $this->print_login();
}
</code>

===Transferring files to Moodle (optional)===
These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.

====get_file_reference($source)====
Rarely does anything other than return the $source param (the default action if not overridden), but takes the 'source' reference from the browser (originally specified in the list returned by 'get_listing') and makes sure it is ready to be passed on to the 'get_file' or 'get_file_by_reference' functions (below).

====get_file($url, $filename = "")====
For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:
* path - the local path where the file was saved
* url - the $url param passed into the function

<code php>
public function get_file($url, $filename = '') {
// Default implementation from the base 'repository' class
$path = $this->prepare_file($filename); // Generate a unique temporary filename
$c = new curl;
$result = $c->download_one($url, null, array('filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT));
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>
<code php>
public function get_file($reference, $filename = '') {
// Slightly extended version taken from repository_equella
global $USER;
// Extract the details saved in the 'source' param by
// repository/equella/callback.php (now in the $reference paramater)
$ref = @unserialize(base64_decode($reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}
$path = $this->prepare_file($filename);
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie'=>$cookiepathname));
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT));
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>

====get_link($url)====
Used with FILE_EXTERNAL to convert a reference (from 'get_file_reference', but ultimately from the output of 'get_listing') into a URL that can be used directly by the end-user's browser. Usually just returns the original $url, but may need further transformation based on the internal implementation of the repository plugin.

{{Moodle 2.3}}====get_file_source_info($source)====
Takes the 'source' field from 'get_listing' (as returned by the user's browser) and 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.

===Search functions (optional)===

These functions allow you to implement search functionality within your repository.

====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 text field element named '''s''', this is where users will type in their search criteria

The following fields are automatically inserted in Moodle 2.3+ (but may need to be manually included in earlier versions):
* 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

<code php>
public function print_search() {
// The default implementation in class 'repository'
global $PAGE;
$renderer = $PAGE->get_renderer('core', 'files');
return $renderer->repository_default_searchform();
}

// From core_files_renderer (repository/renderer.php)
public function repository_default_searchform() {
$str = '<div class="fp-def-search"><input name="s" value='.get_string('search', 'repository').' /></div>';
return $str;
}
</code>

<code php>
public function print_search() {

// 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;
}
</code>

====search($search_text, $page = 0)====
Return the results of doing the search. Any additional parameters from the search form can be retrieved by $param = optional_param('paramname', [defaultvalue], PARAM_INT / PARAM_TEXT);. The return should return an array containing:
* list - with the same layout as the 'list' element in 'get_listing'
<code php>
public function search($search_text, $page = 0) {
// Example from repoistory_googledocs
$gdocs = new google_docs($this->googleoauth);

$ret = array();
$ret['dynload'] = true;
$ret['list'] = $gdocs->get_file_list($search_text);
return $ret;
}
</code>

====global_search()====
Return true if should be included in a search throughout all repositories (currently not available via the UI)

{{Moodle 2.3}}===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_file_lifetime()====
Return minimum number of seconds before checking for changes to the file (default implementation = 1 day)
<code php>
public function get_reference_file_lifetime($ref) {
return 60 * 60 * 24; // One day
}
</code>

====sync_individual_file(stored_file $storedfile)====
Called after the file has reached the 'lifetime' specified above to see if it should now be synchronised (default implementation is to return true)
<code php>
public function sync_individual_file(stored_file $storedfile) {
return true;
}
</code>

====get_reference_details($reference, $filestatus = 0)====
Returns human-readable information about where the original file is stored (to be displayed in the filepicker properties box). It is usually prefixed with repository name and semicolon (e.g. 'Myrepository: http://url.to.file'). $reference is the 'source' output by 'get_listing'. $filestatus can be either 0 (OK - default) or 666 (source file missing).
<code php>
public function get_reference_details($reference, $filestatus = 0) {
// Example taken from repository_equella
if (!$filestatus) {
$ref = unserialize(base64_decode($reference));
return $this->get_name(). ': '. $ref->filename;
} else {
return get_string('lostsource', 'repository', '');
}
}
</code>

====get_file_by_reference($reference)====
Returns up-to-date information about the original file, only called when the 'lifetime' is reached and 'sync_individual_file' returns true.
* for image files - download the file and return either $ret->filepath (full path on the server), $ret->handle (open handle to the file) or $ret->content (raw data from the file) to allow the file to be saved into the Moodle filesystem and the thumbnail to be updated
* for non-image files - avoid downloading the file (if possible) and just return $ret->filesize to update that information
* for missing / inaccessible files - return null
Remember this function may be called quite a lot, as the filemanager often wants to know the filesize.
<code php>
public function get_file_by_reference($reference) {
// Example taken from repository_equella
global $USER;
// Extract the remote file identifier
$ref = @unserialize(base64_decode($reference->reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}

// Download the file details
$return = null;
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie' => $cookiepathname));
if (file_extension_in_typegroup($ref->filename, 'web_image')) {
// The file is an image - download and return the file path
$path = $this->prepare_file('');
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::SYNCIMAGE_TIMEOUT));
if ($result === true) {
$return = (object)array('filepath' => $path);
}
} else {
// The file is not an image - just get the file details
$result = $c->head($url, array('followlocation' => true, 'timeout' => self::SYNCFILE_TIMEOUT));
}
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}

$this->connection_result($c->get_errno());
$curlinfo = $c->get_info();
if ($return === null && isset($curlinfo['http_code']) && $curlinfo['http_code'] == 200
&& array_key_exists('download_content_length', $curlinfo)
&& $curlinfo['download_content_length'] >= 0) {
// we received a correct header and at least can tell the file size
$return = (object)array('filesize' => $curlinfo['download_content_length']);
}
return $return;
}
</code>

====send_file($storedfile, $lifetime=86400, $filter=0, $forcedownload=false, array $options = null)====
Send the requested file back to the user's browser. The 'reference' for the file can be found via $storedfile->get_reference(). If the file is not found / no longer exists, the function 'send_file_not_found()' should be used. Otherwise the file should be output directly, via the most appropriate method - e.g. use a 'Location: ' header to redirect to the external URL; or download the file and cache within the Moodle filesystem (possibly using '$this->import_external_file_contents()'), then call 'send_stored_file'. Note, it is up to the repository developer to decide whether to actually download the file or to return a locally cached copy instead.
<code php>
public function send_file($stored_file, $lifetime=86400 , $filter=0, $forcedownload=false, array $options = null) {
// Example taken from repository_equella
$reference = unserialize(base64_decode($stored_file->get_reference()));
$url = $this->appendtoken($reference->url);
if ($url) {
header('Location: ' . $url);
} else {
send_file_not_found();
}
}
</code>
An example of caching files within the Moodle filesystem can be found in repository_dropbox.

===Misc functions===

A couple of other useful functions to be aware of.

====get_name()====
Returns the human-readable name for this instance of the plugin (the default implementation should usually be fine and this function can be useful when doing any output to the user).

====cron()====
For any background tasks that need to be scheduled (rarely needed). The minimum time between calls is specified in the version.php file (but the maximum time depends on the server settings for the Moodle install).

== I18n - Internationalization ==
These following strings are required in ''moodle/repository/myplugin/lang/en/repository_myplugin.php'' or ''moodle/lang/en/repository_myplugin.php'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T20:57:30Z

Davosmith: /* instance_config_form($mform) */

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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. [[lib/formslib.php Form Definition]] has details of all the types of elements you can add to the settings form.

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

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===User login (optional)===
If the plugin requires login from the user at the time when they use it, then these functions can be used.

====print_login====
Returns an array of the elements required in the login form. If no login form is required, then the default implementation of this will redirect to the files list. If $this->options['ajax'] is not set, then an HTML-snippet with the login fields (but not the form tags) should be output, instead of returning the form details.
<code php>
public function print_login() { // From repository_alfresco
if ($this->options['ajax']) {
$user_field = new stdClass();
$user_field->label = get_string('username', 'repository_alfresco').': ';
$user_field->id = 'alfresco_username';
$user_field->type = 'text';
$user_field->name = 'al_username';

$passwd_field = new stdClass();
$passwd_field->label = get_string('password', 'repository_alfresco').': ';
$passwd_field->id = 'alfresco_password';
$passwd_field->type = 'password';
$passwd_field->name = 'al_password';

$ret = array();
$ret['login'] = array($user_field, $passwd_field);
return $ret;
} else { // Non-AJAX login form - directly output the form elements
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_alfresco').'</label></td>';
echo '<td><input type="text" name="al_username" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_alfresco').'</label></td>';
echo '<td><input type="password" name="al_password" /></td></tr>';
echo '</table>';
echo '<input type="submit" value="Enter" />';
}
}
</code>
This will help to generate a form by file picker which contains user name and password input elements.

For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the '__construct' function, via $submitted = optional_param('fieldname', [defaultvalue], PARAM_INT/PARAM_TEXT).
<code php>
public function __construct($repositoryid, $context = SYSCONTEXTID, $options = array()) {
// Taken from repository_alfresco

/* Skipping code that is not relevant to user login */

$this->alfresco = new Alfresco_Repository($this->options['alfresco_url']);
$this->username = optional_param('al_username', '', PARAM_RAW);
$this->password = optional_param('al_password', '', PARAM_RAW);
try{
// deal with user logging in
if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {
$this->ticket = $this->alfresco->authenticate($this->username, $this->password);
$SESSION->{$this->sessname} = $this->ticket;
} else {
if (!empty($SESSION->{$this->sessname})) {
$this->ticket = $SESSION->{$this->sessname};
}
}
$this->user_session = $this->alfresco->createSession($this->ticket);
$this->store = new SpacesStore($this->user_session);
} catch (Exception $e) {
$this->logout();
}
$this->current_node = null;

/* Skipping code that is not relevant to user login */

}
</code>

Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.
<code php>
public function print_login(){ // Code taken from repository_boxnet
$t = $this->boxclient->getTicket();
if ($this->options['ajax']) {
$popup_btn = new stdClass();
$popup_btn->type = 'popup';
$popup_btn->url = ' https://www.box.com/api/1.0/auth/' . $t['ticket'];

$ret = array();
$ret['login'] = array($popup_btn);
return $ret;
} else {
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_boxnet').'</label></td>';
echo '<td><input type="text" name="boxusername" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_boxnet').'</label></td>';
echo '<td><input type="password" name="boxpassword" /></td></tr>';
echo '<input type="hidden" name="ticket" value="'.$t['ticket'].'" />';
echo '</table>';
echo '<input type="submit" value="'.get_string('enter', 'repository').'" />';
}
}
</code>

====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.
<code php>
public function check_login() { // Taken from repository_alfresco
global $SESSION;
return !empty($SESSION->{$this->sessname});
}
</code>
====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. After this the code should return something suitable to display to the user (usually the results of calling $this->print_login() ):
<code php>
public function logout() { // Taken from repository_alfresco
global $SESSION;
unset($SESSION->{$this->sessname});
return $this->print_login();
}
</code>

===Transferring files to Moodle (optional)===
These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.

====get_file_reference($source)====
Rarely does anything other than return the $source param (the default action if not overridden), but takes the 'source' reference from the browser (originally specified in the list returned by 'get_listing') and makes sure it is ready to be passed on to the 'get_file' or 'get_file_by_reference' functions (below).

====get_file($url, $filename = "")====
For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:
* path - the local path where the file was saved
* url - the $url param passed into the function

<code php>
public function get_file($url, $filename = '') {
// Default implementation from the base 'repository' class
$path = $this->prepare_file($filename); // Generate a unique temporary filename
$c = new curl;
$result = $c->download_one($url, null, array('filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT));
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>
<code php>
public function get_file($reference, $filename = '') {
// Slightly extended version taken from repository_equella
global $USER;
// Extract the details saved in the 'source' param by
// repository/equella/callback.php (now in the $reference paramater)
$ref = @unserialize(base64_decode($reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}
$path = $this->prepare_file($filename);
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie'=>$cookiepathname));
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT));
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>

====get_link($url)====
Used with FILE_EXTERNAL to convert a reference (from 'get_file_reference', but ultimately from the output of 'get_listing') into a URL that can be used directly by the end-user's browser. Usually just returns the original $url, but may need further transformation based on the internal implementation of the repository plugin.

{{Moodle 2.3}}====get_file_source_info($source)====
Takes the 'source' field from 'get_listing' (as returned by the user's browser) and 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.

===Search functions (optional)===

These functions allow you to implement search functionality within your repository.

====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 text field element named '''s''', this is where users will type in their search criteria

The following fields are automatically inserted in Moodle 2.3+ (but may need to be manually included in earlier versions):
* 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

<code php>
public function print_search() {
// The default implementation in class 'repository'
global $PAGE;
$renderer = $PAGE->get_renderer('core', 'files');
return $renderer->repository_default_searchform();
}

// From core_files_renderer (repository/renderer.php)
public function repository_default_searchform() {
$str = '<div class="fp-def-search"><input name="s" value='.get_string('search', 'repository').' /></div>';
return $str;
}
</code>

<code php>
public function print_search() {

// 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;
}
</code>

====search($search_text, $page = 0)====
Return the results of doing the search. Any additional parameters from the search form can be retrieved by $param = optional_param('paramname', [defaultvalue], PARAM_INT / PARAM_TEXT);. The return should return an array containing:
* list - with the same layout as the 'list' element in 'get_listing'
<code php>
public function search($search_text, $page = 0) {
// Example from repoistory_googledocs
$gdocs = new google_docs($this->googleoauth);

$ret = array();
$ret['dynload'] = true;
$ret['list'] = $gdocs->get_file_list($search_text);
return $ret;
}
</code>

====global_search()====
Return true if should be included in a search throughout all repositories (currently not available via the UI)

{{Moodle 2.3}}===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_file_lifetime()====
Return minimum number of seconds before checking for changes to the file (default implementation = 1 day)
<code php>
public function get_reference_file_lifetime($ref) {
return 60 * 60 * 24; // One day
}
</code>

====sync_individual_file(stored_file $storedfile)====
Called after the file has reached the 'lifetime' specified above to see if it should now be synchronised (default implementation is to return true)
<code php>
public function sync_individual_file(stored_file $storedfile) {
return true;
}
</code>

====get_reference_details($reference, $filestatus = 0)====
Returns human-readable information about where the original file is stored (to be displayed in the filepicker properties box). It is usually prefixed with repository name and semicolon (e.g. 'Myrepository: http://url.to.file'). $reference is the 'source' output by 'get_listing'. $filestatus can be either 0 (OK - default) or 666 (source file missing).
<code php>
public function get_reference_details($reference, $filestatus = 0) {
// Example taken from repository_equella
if (!$filestatus) {
$ref = unserialize(base64_decode($reference));
return $this->get_name(). ': '. $ref->filename;
} else {
return get_string('lostsource', 'repository', '');
}
}
</code>

====get_file_by_reference($reference)====
Returns up-to-date information about the original file, only called when the 'lifetime' is reached and 'sync_individual_file' returns true.
* for image files - download the file and return either $ret->filepath (full path on the server), $ret->handle (open handle to the file) or $ret->content (raw data from the file) to allow the file to be saved into the Moodle filesystem and the thumbnail to be updated
* for non-image files - avoid downloading the file (if possible) and just return $ret->filesize to update that information
* for missing / inaccessible files - return null
Remember this function may be called quite a lot, as the filemanager often wants to know the filesize.
<code php>
public function get_file_by_reference($reference) {
// Example taken from repository_equella
global $USER;
// Extract the remote file identifier
$ref = @unserialize(base64_decode($reference->reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}

// Download the file details
$return = null;
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie' => $cookiepathname));
if (file_extension_in_typegroup($ref->filename, 'web_image')) {
// The file is an image - download and return the file path
$path = $this->prepare_file('');
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::SYNCIMAGE_TIMEOUT));
if ($result === true) {
$return = (object)array('filepath' => $path);
}
} else {
// The file is not an image - just get the file details
$result = $c->head($url, array('followlocation' => true, 'timeout' => self::SYNCFILE_TIMEOUT));
}
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}

$this->connection_result($c->get_errno());
$curlinfo = $c->get_info();
if ($return === null && isset($curlinfo['http_code']) && $curlinfo['http_code'] == 200
&& array_key_exists('download_content_length', $curlinfo)
&& $curlinfo['download_content_length'] >= 0) {
// we received a correct header and at least can tell the file size
$return = (object)array('filesize' => $curlinfo['download_content_length']);
}
return $return;
}
</code>

====send_file($storedfile, $lifetime=86400, $filter=0, $forcedownload=false, array $options = null)====
Send the requested file back to the user's browser. The 'reference' for the file can be found via $storedfile->get_reference(). If the file is not found / no longer exists, the function 'send_file_not_found()' should be used. Otherwise the file should be output directly, via the most appropriate method - e.g. use a 'Location: ' header to redirect to the external URL; or download the file and cache within the Moodle filesystem (possibly using '$this->import_external_file_contents()'), then call 'send_stored_file'. Note, it is up to the repository developer to decide whether to actually download the file or to return a locally cached copy instead.
<code php>
public function send_file($stored_file, $lifetime=86400 , $filter=0, $forcedownload=false, array $options = null) {
// Example taken from repository_equella
$reference = unserialize(base64_decode($stored_file->get_reference()));
$url = $this->appendtoken($reference->url);
if ($url) {
header('Location: ' . $url);
} else {
send_file_not_found();
}
}
</code>
An example of caching files within the Moodle filesystem can be found in repository_dropbox.

===Misc functions===

A couple of other useful functions to be aware of.

====get_name()====
Returns the human-readable name for this instance of the plugin (the default implementation should usually be fine and this function can be useful when doing any output to the user).

====cron()====
For any background tasks that need to be scheduled (rarely needed). The minimum time between calls is specified in the version.php file (but the maximum time depends on the server settings for the Moodle install).

== I18n - Internationalization ==
These following strings are required in ''moodle/repository/myplugin/lang/en/repository_myplugin.php'' or ''moodle/lang/en/repository_myplugin.php'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T20:55:12Z

Davosmith: /* Repository APIs */

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===User login (optional)===
If the plugin requires login from the user at the time when they use it, then these functions can be used.

====print_login====
Returns an array of the elements required in the login form. If no login form is required, then the default implementation of this will redirect to the files list. If $this->options['ajax'] is not set, then an HTML-snippet with the login fields (but not the form tags) should be output, instead of returning the form details.
<code php>
public function print_login() { // From repository_alfresco
if ($this->options['ajax']) {
$user_field = new stdClass();
$user_field->label = get_string('username', 'repository_alfresco').': ';
$user_field->id = 'alfresco_username';
$user_field->type = 'text';
$user_field->name = 'al_username';

$passwd_field = new stdClass();
$passwd_field->label = get_string('password', 'repository_alfresco').': ';
$passwd_field->id = 'alfresco_password';
$passwd_field->type = 'password';
$passwd_field->name = 'al_password';

$ret = array();
$ret['login'] = array($user_field, $passwd_field);
return $ret;
} else { // Non-AJAX login form - directly output the form elements
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_alfresco').'</label></td>';
echo '<td><input type="text" name="al_username" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_alfresco').'</label></td>';
echo '<td><input type="password" name="al_password" /></td></tr>';
echo '</table>';
echo '<input type="submit" value="Enter" />';
}
}
</code>
This will help to generate a form by file picker which contains user name and password input elements.

For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the '__construct' function, via $submitted = optional_param('fieldname', [defaultvalue], PARAM_INT/PARAM_TEXT).
<code php>
public function __construct($repositoryid, $context = SYSCONTEXTID, $options = array()) {
// Taken from repository_alfresco

/* Skipping code that is not relevant to user login */

$this->alfresco = new Alfresco_Repository($this->options['alfresco_url']);
$this->username = optional_param('al_username', '', PARAM_RAW);
$this->password = optional_param('al_password', '', PARAM_RAW);
try{
// deal with user logging in
if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {
$this->ticket = $this->alfresco->authenticate($this->username, $this->password);
$SESSION->{$this->sessname} = $this->ticket;
} else {
if (!empty($SESSION->{$this->sessname})) {
$this->ticket = $SESSION->{$this->sessname};
}
}
$this->user_session = $this->alfresco->createSession($this->ticket);
$this->store = new SpacesStore($this->user_session);
} catch (Exception $e) {
$this->logout();
}
$this->current_node = null;

/* Skipping code that is not relevant to user login */

}
</code>

Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.
<code php>
public function print_login(){ // Code taken from repository_boxnet
$t = $this->boxclient->getTicket();
if ($this->options['ajax']) {
$popup_btn = new stdClass();
$popup_btn->type = 'popup';
$popup_btn->url = ' https://www.box.com/api/1.0/auth/' . $t['ticket'];

$ret = array();
$ret['login'] = array($popup_btn);
return $ret;
} else {
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_boxnet').'</label></td>';
echo '<td><input type="text" name="boxusername" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_boxnet').'</label></td>';
echo '<td><input type="password" name="boxpassword" /></td></tr>';
echo '<input type="hidden" name="ticket" value="'.$t['ticket'].'" />';
echo '</table>';
echo '<input type="submit" value="'.get_string('enter', 'repository').'" />';
}
}
</code>

====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.
<code php>
public function check_login() { // Taken from repository_alfresco
global $SESSION;
return !empty($SESSION->{$this->sessname});
}
</code>
====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. After this the code should return something suitable to display to the user (usually the results of calling $this->print_login() ):
<code php>
public function logout() { // Taken from repository_alfresco
global $SESSION;
unset($SESSION->{$this->sessname});
return $this->print_login();
}
</code>

===Transferring files to Moodle (optional)===
These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.

====get_file_reference($source)====
Rarely does anything other than return the $source param (the default action if not overridden), but takes the 'source' reference from the browser (originally specified in the list returned by 'get_listing') and makes sure it is ready to be passed on to the 'get_file' or 'get_file_by_reference' functions (below).

====get_file($url, $filename = "")====
For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:
* path - the local path where the file was saved
* url - the $url param passed into the function

<code php>
public function get_file($url, $filename = '') {
// Default implementation from the base 'repository' class
$path = $this->prepare_file($filename); // Generate a unique temporary filename
$c = new curl;
$result = $c->download_one($url, null, array('filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT));
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>
<code php>
public function get_file($reference, $filename = '') {
// Slightly extended version taken from repository_equella
global $USER;
// Extract the details saved in the 'source' param by
// repository/equella/callback.php (now in the $reference paramater)
$ref = @unserialize(base64_decode($reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}
$path = $this->prepare_file($filename);
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie'=>$cookiepathname));
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT));
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>

====get_link($url)====
Used with FILE_EXTERNAL to convert a reference (from 'get_file_reference', but ultimately from the output of 'get_listing') into a URL that can be used directly by the end-user's browser. Usually just returns the original $url, but may need further transformation based on the internal implementation of the repository plugin.

{{Moodle 2.3}}====get_file_source_info($source)====
Takes the 'source' field from 'get_listing' (as returned by the user's browser) and 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.

===Search functions (optional)===

These functions allow you to implement search functionality within your repository.

====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 text field element named '''s''', this is where users will type in their search criteria

The following fields are automatically inserted in Moodle 2.3+ (but may need to be manually included in earlier versions):
* 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

<code php>
public function print_search() {
// The default implementation in class 'repository'
global $PAGE;
$renderer = $PAGE->get_renderer('core', 'files');
return $renderer->repository_default_searchform();
}

// From core_files_renderer (repository/renderer.php)
public function repository_default_searchform() {
$str = '<div class="fp-def-search"><input name="s" value='.get_string('search', 'repository').' /></div>';
return $str;
}
</code>

<code php>
public function print_search() {

// 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;
}
</code>

====search($search_text, $page = 0)====
Return the results of doing the search. Any additional parameters from the search form can be retrieved by $param = optional_param('paramname', [defaultvalue], PARAM_INT / PARAM_TEXT);. The return should return an array containing:
* list - with the same layout as the 'list' element in 'get_listing'
<code php>
public function search($search_text, $page = 0) {
// Example from repoistory_googledocs
$gdocs = new google_docs($this->googleoauth);

$ret = array();
$ret['dynload'] = true;
$ret['list'] = $gdocs->get_file_list($search_text);
return $ret;
}
</code>

====global_search()====
Return true if should be included in a search throughout all repositories (currently not available via the UI)

{{Moodle 2.3}}===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_file_lifetime()====
Return minimum number of seconds before checking for changes to the file (default implementation = 1 day)
<code php>
public function get_reference_file_lifetime($ref) {
return 60 * 60 * 24; // One day
}
</code>

====sync_individual_file(stored_file $storedfile)====
Called after the file has reached the 'lifetime' specified above to see if it should now be synchronised (default implementation is to return true)
<code php>
public function sync_individual_file(stored_file $storedfile) {
return true;
}
</code>

====get_reference_details($reference, $filestatus = 0)====
Returns human-readable information about where the original file is stored (to be displayed in the filepicker properties box). It is usually prefixed with repository name and semicolon (e.g. 'Myrepository: http://url.to.file'). $reference is the 'source' output by 'get_listing'. $filestatus can be either 0 (OK - default) or 666 (source file missing).
<code php>
public function get_reference_details($reference, $filestatus = 0) {
// Example taken from repository_equella
if (!$filestatus) {
$ref = unserialize(base64_decode($reference));
return $this->get_name(). ': '. $ref->filename;
} else {
return get_string('lostsource', 'repository', '');
}
}
</code>

====get_file_by_reference($reference)====
Returns up-to-date information about the original file, only called when the 'lifetime' is reached and 'sync_individual_file' returns true.
* for image files - download the file and return either $ret->filepath (full path on the server), $ret->handle (open handle to the file) or $ret->content (raw data from the file) to allow the file to be saved into the Moodle filesystem and the thumbnail to be updated
* for non-image files - avoid downloading the file (if possible) and just return $ret->filesize to update that information
* for missing / inaccessible files - return null
Remember this function may be called quite a lot, as the filemanager often wants to know the filesize.
<code php>
public function get_file_by_reference($reference) {
// Example taken from repository_equella
global $USER;
// Extract the remote file identifier
$ref = @unserialize(base64_decode($reference->reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}

// Download the file details
$return = null;
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie' => $cookiepathname));
if (file_extension_in_typegroup($ref->filename, 'web_image')) {
// The file is an image - download and return the file path
$path = $this->prepare_file('');
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::SYNCIMAGE_TIMEOUT));
if ($result === true) {
$return = (object)array('filepath' => $path);
}
} else {
// The file is not an image - just get the file details
$result = $c->head($url, array('followlocation' => true, 'timeout' => self::SYNCFILE_TIMEOUT));
}
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}

$this->connection_result($c->get_errno());
$curlinfo = $c->get_info();
if ($return === null && isset($curlinfo['http_code']) && $curlinfo['http_code'] == 200
&& array_key_exists('download_content_length', $curlinfo)
&& $curlinfo['download_content_length'] >= 0) {
// we received a correct header and at least can tell the file size
$return = (object)array('filesize' => $curlinfo['download_content_length']);
}
return $return;
}
</code>

====send_file($storedfile, $lifetime=86400, $filter=0, $forcedownload=false, array $options = null)====
Send the requested file back to the user's browser. The 'reference' for the file can be found via $storedfile->get_reference(). If the file is not found / no longer exists, the function 'send_file_not_found()' should be used. Otherwise the file should be output directly, via the most appropriate method - e.g. use a 'Location: ' header to redirect to the external URL; or download the file and cache within the Moodle filesystem (possibly using '$this->import_external_file_contents()'), then call 'send_stored_file'. Note, it is up to the repository developer to decide whether to actually download the file or to return a locally cached copy instead.
<code php>
public function send_file($stored_file, $lifetime=86400 , $filter=0, $forcedownload=false, array $options = null) {
// Example taken from repository_equella
$reference = unserialize(base64_decode($stored_file->get_reference()));
$url = $this->appendtoken($reference->url);
if ($url) {
header('Location: ' . $url);
} else {
send_file_not_found();
}
}
</code>
An example of caching files within the Moodle filesystem can be found in repository_dropbox.

===Misc functions===

A couple of other useful functions to be aware of.

====get_name()====
Returns the human-readable name for this instance of the plugin (the default implementation should usually be fine and this function can be useful when doing any output to the user).

====cron()====
For any background tasks that need to be scheduled (rarely needed). The minimum time between calls is specified in the version.php file (but the maximum time depends on the server settings for the Moodle install).

== I18n - Internationalization ==
These following strings are required in ''moodle/repository/myplugin/lang/en/repository_myplugin.php'' or ''moodle/lang/en/repository_myplugin.php'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T20:44:24Z

Davosmith: /* get_file_source_info($source) (2.3+) */

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===User login (optional)===
If the plugin requires login from the user at the time when they use it, then these functions can be used.

====print_login====
Returns an array of the elements required in the login form. If no login form is required, then the default implementation of this will redirect to the files list. If $this->options['ajax'] is not set, then an HTML-snippet with the login fields (but not the form tags) should be output, instead of returning the form details.
<code php>
public function print_login() { // From repository_alfresco
if ($this->options['ajax']) {
$user_field = new stdClass();
$user_field->label = get_string('username', 'repository_alfresco').': ';
$user_field->id = 'alfresco_username';
$user_field->type = 'text';
$user_field->name = 'al_username';

$passwd_field = new stdClass();
$passwd_field->label = get_string('password', 'repository_alfresco').': ';
$passwd_field->id = 'alfresco_password';
$passwd_field->type = 'password';
$passwd_field->name = 'al_password';

$ret = array();
$ret['login'] = array($user_field, $passwd_field);
return $ret;
} else { // Non-AJAX login form - directly output the form elements
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_alfresco').'</label></td>';
echo '<td><input type="text" name="al_username" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_alfresco').'</label></td>';
echo '<td><input type="password" name="al_password" /></td></tr>';
echo '</table>';
echo '<input type="submit" value="Enter" />';
}
}
</code>
This will help to generate a form by file picker which contains user name and password input elements.

For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the '__construct' function, via $submitted = optional_param('fieldname', [defaultvalue], PARAM_INT/PARAM_TEXT).
<code php>
public function __construct($repositoryid, $context = SYSCONTEXTID, $options = array()) {
// Taken from repository_alfresco

/* Skipping code that is not relevant to user login */

$this->alfresco = new Alfresco_Repository($this->options['alfresco_url']);
$this->username = optional_param('al_username', '', PARAM_RAW);
$this->password = optional_param('al_password', '', PARAM_RAW);
try{
// deal with user logging in
if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {
$this->ticket = $this->alfresco->authenticate($this->username, $this->password);
$SESSION->{$this->sessname} = $this->ticket;
} else {
if (!empty($SESSION->{$this->sessname})) {
$this->ticket = $SESSION->{$this->sessname};
}
}
$this->user_session = $this->alfresco->createSession($this->ticket);
$this->store = new SpacesStore($this->user_session);
} catch (Exception $e) {
$this->logout();
}
$this->current_node = null;

/* Skipping code that is not relevant to user login */

}
</code>

Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.
<code php>
public function print_login(){ // Code taken from repository_boxnet
$t = $this->boxclient->getTicket();
if ($this->options['ajax']) {
$popup_btn = new stdClass();
$popup_btn->type = 'popup';
$popup_btn->url = ' https://www.box.com/api/1.0/auth/' . $t['ticket'];

$ret = array();
$ret['login'] = array($popup_btn);
return $ret;
} else {
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_boxnet').'</label></td>';
echo '<td><input type="text" name="boxusername" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_boxnet').'</label></td>';
echo '<td><input type="password" name="boxpassword" /></td></tr>';
echo '<input type="hidden" name="ticket" value="'.$t['ticket'].'" />';
echo '</table>';
echo '<input type="submit" value="'.get_string('enter', 'repository').'" />';
}
}
</code>

====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.
<code php>
public function check_login() { // Taken from repository_alfresco
global $SESSION;
return !empty($SESSION->{$this->sessname});
}
</code>
====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. After this the code should return something suitable to display to the user (usually the results of calling $this->print_login() ):
<code php>
public function logout() { // Taken from repository_alfresco
global $SESSION;
unset($SESSION->{$this->sessname});
return $this->print_login();
}
</code>

===Transferring files to Moodle (optional)===
These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.

====get_file_reference($source)====
Rarely does anything other than return the $source param (the default action if not overridden), but takes the 'source' reference from the browser (originally specified in the list returned by 'get_listing') and makes sure it is ready to be passed on to the 'get_file' or 'get_file_by_reference' functions (below).

====get_file($url, $filename = "")====
For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:
* path - the local path where the file was saved
* url - the $url param passed into the function

<code php>
public function get_file($url, $filename = '') {
// Default implementation from the base 'repository' class
$path = $this->prepare_file($filename); // Generate a unique temporary filename
$c = new curl;
$result = $c->download_one($url, null, array('filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT));
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>
<code php>
public function get_file($reference, $filename = '') {
// Slightly extended version taken from repository_equella
global $USER;
// Extract the details saved in the 'source' param by
// repository/equella/callback.php (now in the $reference paramater)
$ref = @unserialize(base64_decode($reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}
$path = $this->prepare_file($filename);
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie'=>$cookiepathname));
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT));
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>

====get_link($url)====
Used with FILE_EXTERNAL to convert a reference (from 'get_file_reference', but ultimately from the output of 'get_listing') into a URL that can be used directly by the end-user's browser. Usually just returns the original $url, but may need further transformation based on the internal implementation of the repository plugin.

{{Moodle 2.3}}====get_file_source_info($source)====
Takes the 'source' field from 'get_listing' (as returned by the user's browser) and 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.

===Search functions (optional)===

These functions allow you to implement search functionality within your repository.

====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 text field element named '''s''', this is where users will type in their search criteria

The following fields are automatically inserted in Moodle 2.3+ (but may need to be manually included in earlier versions):
* 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

<code php>
public function print_search() {
// The default implementation in class 'repository'
global $PAGE;
$renderer = $PAGE->get_renderer('core', 'files');
return $renderer->repository_default_searchform();
}

// From core_files_renderer (repository/renderer.php)
public function repository_default_searchform() {
$str = '<div class="fp-def-search"><input name="s" value='.get_string('search', 'repository').' /></div>';
return $str;
}
</code>

<code php>
public function print_search() {

// 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;
}
</code>

====search($search_text, $page = 0)====
Return the results of doing the search. Any additional parameters from the search form can be retrieved by $param = optional_param('paramname', [defaultvalue], PARAM_INT / PARAM_TEXT);. The return should return an array containing:
* list - with the same layout as the 'list' element in 'get_listing'
<code php>
public function search($search_text, $page = 0) {
// Example from repoistory_googledocs
$gdocs = new google_docs($this->googleoauth);

$ret = array();
$ret['dynload'] = true;
$ret['list'] = $gdocs->get_file_list($search_text);
return $ret;
}
</code>

====global_search()====
Return true if should be included in a search throughout all repositories (currently not available via the UI)

{{Moodle 2.3}}===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.

===Misc functions===

A couple of other useful functions to be aware of.

====get_name()====
Returns the human-readable name for this instance of the plugin (the default implementation should usually be fine and this function can be useful when doing any output to the user).

====cron()====
For any background tasks that need to be scheduled (rarely needed). The minimum time between calls is specified in the version.php file (but the maximum time depends on the server settings for the Moodle install).

== I18n - Internationalization ==
These following strings are required in ''moodle/repository/myplugin/lang/en/repository_myplugin.php'' or ''moodle/lang/en/repository_myplugin.php'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T20:43:58Z

Davosmith: /* Repository support for returning file as alias/shortcut */

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===User login (optional)===
If the plugin requires login from the user at the time when they use it, then these functions can be used.

====print_login====
Returns an array of the elements required in the login form. If no login form is required, then the default implementation of this will redirect to the files list. If $this->options['ajax'] is not set, then an HTML-snippet with the login fields (but not the form tags) should be output, instead of returning the form details.
<code php>
public function print_login() { // From repository_alfresco
if ($this->options['ajax']) {
$user_field = new stdClass();
$user_field->label = get_string('username', 'repository_alfresco').': ';
$user_field->id = 'alfresco_username';
$user_field->type = 'text';
$user_field->name = 'al_username';

$passwd_field = new stdClass();
$passwd_field->label = get_string('password', 'repository_alfresco').': ';
$passwd_field->id = 'alfresco_password';
$passwd_field->type = 'password';
$passwd_field->name = 'al_password';

$ret = array();
$ret['login'] = array($user_field, $passwd_field);
return $ret;
} else { // Non-AJAX login form - directly output the form elements
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_alfresco').'</label></td>';
echo '<td><input type="text" name="al_username" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_alfresco').'</label></td>';
echo '<td><input type="password" name="al_password" /></td></tr>';
echo '</table>';
echo '<input type="submit" value="Enter" />';
}
}
</code>
This will help to generate a form by file picker which contains user name and password input elements.

For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the '__construct' function, via $submitted = optional_param('fieldname', [defaultvalue], PARAM_INT/PARAM_TEXT).
<code php>
public function __construct($repositoryid, $context = SYSCONTEXTID, $options = array()) {
// Taken from repository_alfresco

/* Skipping code that is not relevant to user login */

$this->alfresco = new Alfresco_Repository($this->options['alfresco_url']);
$this->username = optional_param('al_username', '', PARAM_RAW);
$this->password = optional_param('al_password', '', PARAM_RAW);
try{
// deal with user logging in
if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {
$this->ticket = $this->alfresco->authenticate($this->username, $this->password);
$SESSION->{$this->sessname} = $this->ticket;
} else {
if (!empty($SESSION->{$this->sessname})) {
$this->ticket = $SESSION->{$this->sessname};
}
}
$this->user_session = $this->alfresco->createSession($this->ticket);
$this->store = new SpacesStore($this->user_session);
} catch (Exception $e) {
$this->logout();
}
$this->current_node = null;

/* Skipping code that is not relevant to user login */

}
</code>

Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.
<code php>
public function print_login(){ // Code taken from repository_boxnet
$t = $this->boxclient->getTicket();
if ($this->options['ajax']) {
$popup_btn = new stdClass();
$popup_btn->type = 'popup';
$popup_btn->url = ' https://www.box.com/api/1.0/auth/' . $t['ticket'];

$ret = array();
$ret['login'] = array($popup_btn);
return $ret;
} else {
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_boxnet').'</label></td>';
echo '<td><input type="text" name="boxusername" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_boxnet').'</label></td>';
echo '<td><input type="password" name="boxpassword" /></td></tr>';
echo '<input type="hidden" name="ticket" value="'.$t['ticket'].'" />';
echo '</table>';
echo '<input type="submit" value="'.get_string('enter', 'repository').'" />';
}
}
</code>

====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.
<code php>
public function check_login() { // Taken from repository_alfresco
global $SESSION;
return !empty($SESSION->{$this->sessname});
}
</code>
====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. After this the code should return something suitable to display to the user (usually the results of calling $this->print_login() ):
<code php>
public function logout() { // Taken from repository_alfresco
global $SESSION;
unset($SESSION->{$this->sessname});
return $this->print_login();
}
</code>

===Transferring files to Moodle (optional)===
These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.

====get_file_reference($source)====
Rarely does anything other than return the $source param (the default action if not overridden), but takes the 'source' reference from the browser (originally specified in the list returned by 'get_listing') and makes sure it is ready to be passed on to the 'get_file' or 'get_file_by_reference' functions (below).

====get_file($url, $filename = "")====
For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:
* path - the local path where the file was saved
* url - the $url param passed into the function

<code php>
public function get_file($url, $filename = '') {
// Default implementation from the base 'repository' class
$path = $this->prepare_file($filename); // Generate a unique temporary filename
$c = new curl;
$result = $c->download_one($url, null, array('filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT));
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>
<code php>
public function get_file($reference, $filename = '') {
// Slightly extended version taken from repository_equella
global $USER;
// Extract the details saved in the 'source' param by
// repository/equella/callback.php (now in the $reference paramater)
$ref = @unserialize(base64_decode($reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}
$path = $this->prepare_file($filename);
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie'=>$cookiepathname));
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT));
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>

====get_link($url)====
Used with FILE_EXTERNAL to convert a reference (from 'get_file_reference', but ultimately from the output of 'get_listing') into a URL that can be used directly by the end-user's browser. Usually just returns the original $url, but may need further transformation based on the internal implementation of the repository plugin.

====get_file_source_info($source) (2.3+)====
Takes the 'source' field from 'get_listing' (as returned by the user's browser) and 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.

===Search functions (optional)===

These functions allow you to implement search functionality within your repository.

====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 text field element named '''s''', this is where users will type in their search criteria

The following fields are automatically inserted in Moodle 2.3+ (but may need to be manually included in earlier versions):
* 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

<code php>
public function print_search() {
// The default implementation in class 'repository'
global $PAGE;
$renderer = $PAGE->get_renderer('core', 'files');
return $renderer->repository_default_searchform();
}

// From core_files_renderer (repository/renderer.php)
public function repository_default_searchform() {
$str = '<div class="fp-def-search"><input name="s" value='.get_string('search', 'repository').' /></div>';
return $str;
}
</code>

<code php>
public function print_search() {

// 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;
}
</code>

====search($search_text, $page = 0)====
Return the results of doing the search. Any additional parameters from the search form can be retrieved by $param = optional_param('paramname', [defaultvalue], PARAM_INT / PARAM_TEXT);. The return should return an array containing:
* list - with the same layout as the 'list' element in 'get_listing'
<code php>
public function search($search_text, $page = 0) {
// Example from repoistory_googledocs
$gdocs = new google_docs($this->googleoauth);

$ret = array();
$ret['dynload'] = true;
$ret['list'] = $gdocs->get_file_list($search_text);
return $ret;
}
</code>

====global_search()====
Return true if should be included in a search throughout all repositories (currently not available via the UI)

{{Moodle 2.3}}===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.

===Misc functions===

A couple of other useful functions to be aware of.

====get_name()====
Returns the human-readable name for this instance of the plugin (the default implementation should usually be fine and this function can be useful when doing any output to the user).

====cron()====
For any background tasks that need to be scheduled (rarely needed). The minimum time between calls is specified in the version.php file (but the maximum time depends on the server settings for the Moodle install).

== I18n - Internationalization ==
These following strings are required in ''moodle/repository/myplugin/lang/en/repository_myplugin.php'' or ''moodle/lang/en/repository_myplugin.php'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T20:41:59Z

Davosmith: /* Repository APIs */

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===User login (optional)===
If the plugin requires login from the user at the time when they use it, then these functions can be used.

====print_login====
Returns an array of the elements required in the login form. If no login form is required, then the default implementation of this will redirect to the files list. If $this->options['ajax'] is not set, then an HTML-snippet with the login fields (but not the form tags) should be output, instead of returning the form details.
<code php>
public function print_login() { // From repository_alfresco
if ($this->options['ajax']) {
$user_field = new stdClass();
$user_field->label = get_string('username', 'repository_alfresco').': ';
$user_field->id = 'alfresco_username';
$user_field->type = 'text';
$user_field->name = 'al_username';

$passwd_field = new stdClass();
$passwd_field->label = get_string('password', 'repository_alfresco').': ';
$passwd_field->id = 'alfresco_password';
$passwd_field->type = 'password';
$passwd_field->name = 'al_password';

$ret = array();
$ret['login'] = array($user_field, $passwd_field);
return $ret;
} else { // Non-AJAX login form - directly output the form elements
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_alfresco').'</label></td>';
echo '<td><input type="text" name="al_username" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_alfresco').'</label></td>';
echo '<td><input type="password" name="al_password" /></td></tr>';
echo '</table>';
echo '<input type="submit" value="Enter" />';
}
}
</code>
This will help to generate a form by file picker which contains user name and password input elements.

For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the '__construct' function, via $submitted = optional_param('fieldname', [defaultvalue], PARAM_INT/PARAM_TEXT).
<code php>
public function __construct($repositoryid, $context = SYSCONTEXTID, $options = array()) {
// Taken from repository_alfresco

/* Skipping code that is not relevant to user login */

$this->alfresco = new Alfresco_Repository($this->options['alfresco_url']);
$this->username = optional_param('al_username', '', PARAM_RAW);
$this->password = optional_param('al_password', '', PARAM_RAW);
try{
// deal with user logging in
if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {
$this->ticket = $this->alfresco->authenticate($this->username, $this->password);
$SESSION->{$this->sessname} = $this->ticket;
} else {
if (!empty($SESSION->{$this->sessname})) {
$this->ticket = $SESSION->{$this->sessname};
}
}
$this->user_session = $this->alfresco->createSession($this->ticket);
$this->store = new SpacesStore($this->user_session);
} catch (Exception $e) {
$this->logout();
}
$this->current_node = null;

/* Skipping code that is not relevant to user login */

}
</code>

Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.
<code php>
public function print_login(){ // Code taken from repository_boxnet
$t = $this->boxclient->getTicket();
if ($this->options['ajax']) {
$popup_btn = new stdClass();
$popup_btn->type = 'popup';
$popup_btn->url = ' https://www.box.com/api/1.0/auth/' . $t['ticket'];

$ret = array();
$ret['login'] = array($popup_btn);
return $ret;
} else {
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_boxnet').'</label></td>';
echo '<td><input type="text" name="boxusername" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_boxnet').'</label></td>';
echo '<td><input type="password" name="boxpassword" /></td></tr>';
echo '<input type="hidden" name="ticket" value="'.$t['ticket'].'" />';
echo '</table>';
echo '<input type="submit" value="'.get_string('enter', 'repository').'" />';
}
}
</code>

====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.
<code php>
public function check_login() { // Taken from repository_alfresco
global $SESSION;
return !empty($SESSION->{$this->sessname});
}
</code>
====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. After this the code should return something suitable to display to the user (usually the results of calling $this->print_login() ):
<code php>
public function logout() { // Taken from repository_alfresco
global $SESSION;
unset($SESSION->{$this->sessname});
return $this->print_login();
}
</code>

===Transferring files to Moodle (optional)===
These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.

====get_file_reference($source)====
Rarely does anything other than return the $source param (the default action if not overridden), but takes the 'source' reference from the browser (originally specified in the list returned by 'get_listing') and makes sure it is ready to be passed on to the 'get_file' or 'get_file_by_reference' functions (below).

====get_file($url, $filename = "")====
For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:
* path - the local path where the file was saved
* url - the $url param passed into the function

<code php>
public function get_file($url, $filename = '') {
// Default implementation from the base 'repository' class
$path = $this->prepare_file($filename); // Generate a unique temporary filename
$c = new curl;
$result = $c->download_one($url, null, array('filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT));
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>
<code php>
public function get_file($reference, $filename = '') {
// Slightly extended version taken from repository_equella
global $USER;
// Extract the details saved in the 'source' param by
// repository/equella/callback.php (now in the $reference paramater)
$ref = @unserialize(base64_decode($reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}
$path = $this->prepare_file($filename);
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie'=>$cookiepathname));
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT));
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>

====get_link($url)====
Used with FILE_EXTERNAL to convert a reference (from 'get_file_reference', but ultimately from the output of 'get_listing') into a URL that can be used directly by the end-user's browser. Usually just returns the original $url, but may need further transformation based on the internal implementation of the repository plugin.

====get_file_source_info($source) (2.3+)====
Takes the 'source' field from 'get_listing' (as returned by the user's browser) and 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.

===Search functions (optional)===

These functions allow you to implement search functionality within your repository.

====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 text field element named '''s''', this is where users will type in their search criteria

The following fields are automatically inserted in Moodle 2.3+ (but may need to be manually included in earlier versions):
* 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

<code php>
public function print_search() {
// The default implementation in class 'repository'
global $PAGE;
$renderer = $PAGE->get_renderer('core', 'files');
return $renderer->repository_default_searchform();
}

// From core_files_renderer (repository/renderer.php)
public function repository_default_searchform() {
$str = '<div class="fp-def-search"><input name="s" value='.get_string('search', 'repository').' /></div>';
return $str;
}
</code>

<code php>
public function print_search() {

// 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;
}
</code>

====search($search_text, $page = 0)====
Return the results of doing the search. Any additional parameters from the search form can be retrieved by $param = optional_param('paramname', [defaultvalue], PARAM_INT / PARAM_TEXT);. The return should return an array containing:
* list - with the same layout as the 'list' element in 'get_listing'
<code php>
public function search($search_text, $page = 0) {
// Example from repoistory_googledocs
$gdocs = new google_docs($this->googleoauth);

$ret = array();
$ret['dynload'] = true;
$ret['list'] = $gdocs->get_file_list($search_text);
return $ret;
}
</code>

====global_search()====
Return true if should be included in a search throughout all repositories (currently not available via the UI)

===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.

===Misc functions===

A couple of other useful functions to be aware of.

====get_name()====
Returns the human-readable name for this instance of the plugin (the default implementation should usually be fine and this function can be useful when doing any output to the user).

====cron()====
For any background tasks that need to be scheduled (rarely needed). The minimum time between calls is specified in the version.php file (but the maximum time depends on the server settings for the Moodle install).

== I18n - Internationalization ==
These following strings are required in ''moodle/repository/myplugin/lang/en/repository_myplugin.php'' or ''moodle/lang/en/repository_myplugin.php'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T20:41:26Z

Davosmith: /* Search functions (optional) */

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===User login (optional)===
If the plugin requires login from the user at the time when they use it, then these functions can be used.

====print_login====
Returns an array of the elements required in the login form. If no login form is required, then the default implementation of this will redirect to the files list. If $this->options['ajax'] is not set, then an HTML-snippet with the login fields (but not the form tags) should be output, instead of returning the form details.
<code php>
public function print_login() { // From repository_alfresco
if ($this->options['ajax']) {
$user_field = new stdClass();
$user_field->label = get_string('username', 'repository_alfresco').': ';
$user_field->id = 'alfresco_username';
$user_field->type = 'text';
$user_field->name = 'al_username';

$passwd_field = new stdClass();
$passwd_field->label = get_string('password', 'repository_alfresco').': ';
$passwd_field->id = 'alfresco_password';
$passwd_field->type = 'password';
$passwd_field->name = 'al_password';

$ret = array();
$ret['login'] = array($user_field, $passwd_field);
return $ret;
} else { // Non-AJAX login form - directly output the form elements
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_alfresco').'</label></td>';
echo '<td><input type="text" name="al_username" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_alfresco').'</label></td>';
echo '<td><input type="password" name="al_password" /></td></tr>';
echo '</table>';
echo '<input type="submit" value="Enter" />';
}
}
</code>
This will help to generate a form by file picker which contains user name and password input elements.

For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the '__construct' function, via $submitted = optional_param('fieldname', [defaultvalue], PARAM_INT/PARAM_TEXT).
<code php>
public function __construct($repositoryid, $context = SYSCONTEXTID, $options = array()) {
// Taken from repository_alfresco

/* Skipping code that is not relevant to user login */

$this->alfresco = new Alfresco_Repository($this->options['alfresco_url']);
$this->username = optional_param('al_username', '', PARAM_RAW);
$this->password = optional_param('al_password', '', PARAM_RAW);
try{
// deal with user logging in
if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {
$this->ticket = $this->alfresco->authenticate($this->username, $this->password);
$SESSION->{$this->sessname} = $this->ticket;
} else {
if (!empty($SESSION->{$this->sessname})) {
$this->ticket = $SESSION->{$this->sessname};
}
}
$this->user_session = $this->alfresco->createSession($this->ticket);
$this->store = new SpacesStore($this->user_session);
} catch (Exception $e) {
$this->logout();
}
$this->current_node = null;

/* Skipping code that is not relevant to user login */

}
</code>

Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.
<code php>
public function print_login(){ // Code taken from repository_boxnet
$t = $this->boxclient->getTicket();
if ($this->options['ajax']) {
$popup_btn = new stdClass();
$popup_btn->type = 'popup';
$popup_btn->url = ' https://www.box.com/api/1.0/auth/' . $t['ticket'];

$ret = array();
$ret['login'] = array($popup_btn);
return $ret;
} else {
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_boxnet').'</label></td>';
echo '<td><input type="text" name="boxusername" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_boxnet').'</label></td>';
echo '<td><input type="password" name="boxpassword" /></td></tr>';
echo '<input type="hidden" name="ticket" value="'.$t['ticket'].'" />';
echo '</table>';
echo '<input type="submit" value="'.get_string('enter', 'repository').'" />';
}
}
</code>

====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.
<code php>
public function check_login() { // Taken from repository_alfresco
global $SESSION;
return !empty($SESSION->{$this->sessname});
}
</code>
====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. After this the code should return something suitable to display to the user (usually the results of calling $this->print_login() ):
<code php>
public function logout() { // Taken from repository_alfresco
global $SESSION;
unset($SESSION->{$this->sessname});
return $this->print_login();
}
</code>

===Transferring files to Moodle (optional)===
These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.

====get_file_reference($source)====
Rarely does anything other than return the $source param (the default action if not overridden), but takes the 'source' reference from the browser (originally specified in the list returned by 'get_listing') and makes sure it is ready to be passed on to the 'get_file' or 'get_file_by_reference' functions (below).

====get_file($url, $filename = "")====
For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:
* path - the local path where the file was saved
* url - the $url param passed into the function

<code php>
public function get_file($url, $filename = '') {
// Default implementation from the base 'repository' class
$path = $this->prepare_file($filename); // Generate a unique temporary filename
$c = new curl;
$result = $c->download_one($url, null, array('filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT));
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>
<code php>
public function get_file($reference, $filename = '') {
// Slightly extended version taken from repository_equella
global $USER;
// Extract the details saved in the 'source' param by
// repository/equella/callback.php (now in the $reference paramater)
$ref = @unserialize(base64_decode($reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}
$path = $this->prepare_file($filename);
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie'=>$cookiepathname));
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT));
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>

====get_link($url)====
Used with FILE_EXTERNAL to convert a reference (from 'get_file_reference', but ultimately from the output of 'get_listing') into a URL that can be used directly by the end-user's browser. Usually just returns the original $url, but may need further transformation based on the internal implementation of the repository plugin.

====get_file_source_info($source) (2.3+)====
Takes the 'source' field from 'get_listing' (as returned by the user's browser) and 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.

===Search functions (optional)===

These functions allow you to implement search functionality within your repository.

====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 text field element named '''s''', this is where users will type in their search criteria

The following fields are automatically inserted in Moodle 2.3+ (but may need to be manually included in earlier versions):
* 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

<code php>
public function print_search() {
// The default implementation in class 'repository'
global $PAGE;
$renderer = $PAGE->get_renderer('core', 'files');
return $renderer->repository_default_searchform();
}

// From core_files_renderer (repository/renderer.php)
public function repository_default_searchform() {
$str = '<div class="fp-def-search"><input name="s" value='.get_string('search', 'repository').' /></div>';
return $str;
}
</code>

<code php>
public function print_search() {

// 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;
}
</code>

====search($search_text, $page = 0)====
Return the results of doing the search. Any additional parameters from the search form can be retrieved by $param = optional_param('paramname', [defaultvalue], PARAM_INT / PARAM_TEXT);. The return should return an array containing:
* list - with the same layout as the 'list' element in 'get_listing'
<code php>
public function search($search_text, $page = 0) {
// Example from repoistory_googledocs
$gdocs = new google_docs($this->googleoauth);

$ret = array();
$ret['dynload'] = true;
$ret['list'] = $gdocs->get_file_list($search_text);
return $ret;
}
</code>

====global_search()====
Return true if should be included in a search throughout all repositories (currently not available via the UI)

===Misc functions===

A couple of other useful functions to be aware of.

====get_name()====
Returns the human-readable name for this instance of the plugin (the default implementation should usually be fine and this function can be useful when doing any output to the user).

====cron()====
For any background tasks that need to be scheduled (rarely needed). The minimum time between calls is specified in the version.php file (but the maximum time depends on the server settings for the Moodle install).

===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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T20:36:33Z

Davosmith: /* print_search */

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===User login (optional)===
If the plugin requires login from the user at the time when they use it, then these functions can be used.

====print_login====
Returns an array of the elements required in the login form. If no login form is required, then the default implementation of this will redirect to the files list. If $this->options['ajax'] is not set, then an HTML-snippet with the login fields (but not the form tags) should be output, instead of returning the form details.
<code php>
public function print_login() { // From repository_alfresco
if ($this->options['ajax']) {
$user_field = new stdClass();
$user_field->label = get_string('username', 'repository_alfresco').': ';
$user_field->id = 'alfresco_username';
$user_field->type = 'text';
$user_field->name = 'al_username';

$passwd_field = new stdClass();
$passwd_field->label = get_string('password', 'repository_alfresco').': ';
$passwd_field->id = 'alfresco_password';
$passwd_field->type = 'password';
$passwd_field->name = 'al_password';

$ret = array();
$ret['login'] = array($user_field, $passwd_field);
return $ret;
} else { // Non-AJAX login form - directly output the form elements
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_alfresco').'</label></td>';
echo '<td><input type="text" name="al_username" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_alfresco').'</label></td>';
echo '<td><input type="password" name="al_password" /></td></tr>';
echo '</table>';
echo '<input type="submit" value="Enter" />';
}
}
</code>
This will help to generate a form by file picker which contains user name and password input elements.

For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the '__construct' function, via $submitted = optional_param('fieldname', [defaultvalue], PARAM_INT/PARAM_TEXT).
<code php>
public function __construct($repositoryid, $context = SYSCONTEXTID, $options = array()) {
// Taken from repository_alfresco

/* Skipping code that is not relevant to user login */

$this->alfresco = new Alfresco_Repository($this->options['alfresco_url']);
$this->username = optional_param('al_username', '', PARAM_RAW);
$this->password = optional_param('al_password', '', PARAM_RAW);
try{
// deal with user logging in
if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {
$this->ticket = $this->alfresco->authenticate($this->username, $this->password);
$SESSION->{$this->sessname} = $this->ticket;
} else {
if (!empty($SESSION->{$this->sessname})) {
$this->ticket = $SESSION->{$this->sessname};
}
}
$this->user_session = $this->alfresco->createSession($this->ticket);
$this->store = new SpacesStore($this->user_session);
} catch (Exception $e) {
$this->logout();
}
$this->current_node = null;

/* Skipping code that is not relevant to user login */

}
</code>

Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.
<code php>
public function print_login(){ // Code taken from repository_boxnet
$t = $this->boxclient->getTicket();
if ($this->options['ajax']) {
$popup_btn = new stdClass();
$popup_btn->type = 'popup';
$popup_btn->url = ' https://www.box.com/api/1.0/auth/' . $t['ticket'];

$ret = array();
$ret['login'] = array($popup_btn);
return $ret;
} else {
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_boxnet').'</label></td>';
echo '<td><input type="text" name="boxusername" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_boxnet').'</label></td>';
echo '<td><input type="password" name="boxpassword" /></td></tr>';
echo '<input type="hidden" name="ticket" value="'.$t['ticket'].'" />';
echo '</table>';
echo '<input type="submit" value="'.get_string('enter', 'repository').'" />';
}
}
</code>

====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.
<code php>
public function check_login() { // Taken from repository_alfresco
global $SESSION;
return !empty($SESSION->{$this->sessname});
}
</code>
====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. After this the code should return something suitable to display to the user (usually the results of calling $this->print_login() ):
<code php>
public function logout() { // Taken from repository_alfresco
global $SESSION;
unset($SESSION->{$this->sessname});
return $this->print_login();
}
</code>

===Transferring files to Moodle (optional)===
These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.

====get_file_reference($source)====
Rarely does anything other than return the $source param (the default action if not overridden), but takes the 'source' reference from the browser (originally specified in the list returned by 'get_listing') and makes sure it is ready to be passed on to the 'get_file' or 'get_file_by_reference' functions (below).

====get_file($url, $filename = "")====
For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:
* path - the local path where the file was saved
* url - the $url param passed into the function

<code php>
public function get_file($url, $filename = '') {
// Default implementation from the base 'repository' class
$path = $this->prepare_file($filename); // Generate a unique temporary filename
$c = new curl;
$result = $c->download_one($url, null, array('filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT));
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>
<code php>
public function get_file($reference, $filename = '') {
// Slightly extended version taken from repository_equella
global $USER;
// Extract the details saved in the 'source' param by
// repository/equella/callback.php (now in the $reference paramater)
$ref = @unserialize(base64_decode($reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}
$path = $this->prepare_file($filename);
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie'=>$cookiepathname));
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT));
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>

====get_link($url)====
Used with FILE_EXTERNAL to convert a reference (from 'get_file_reference', but ultimately from the output of 'get_listing') into a URL that can be used directly by the end-user's browser. Usually just returns the original $url, but may need further transformation based on the internal implementation of the repository plugin.

====get_file_source_info($source) (2.3+)====
Takes the 'source' field from 'get_listing' (as returned by the user's browser) and 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.

===Search functions (optional)===

====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 text field element named '''s''', this is where users will type in their search criteria

The following fields are automatically inserted in Moodle 2.3+ (but may need to be manually included in earlier versions):
* 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

<code php>
public function print_search() {
// The default implementation in class 'repository'
global $PAGE;
$renderer = $PAGE->get_renderer('core', 'files');
return $renderer->repository_default_searchform();
}

// From core_files_renderer (repository/renderer.php)
public function repository_default_searchform() {
$str = '<div class="fp-def-search"><input name="s" value='.get_string('search', 'repository').' /></div>';
return $str;
}
</code>

<code php>
class repository_myrepo extends repository {
// other required functions
....
public function search($search_text, $page = 0) { // Since Moodle 2.3, the page argument is required

// 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;
}
}
</code>

====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_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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T20:32:55Z

Davosmith: /* Transferring files to Moodle (optional) */

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===User login (optional)===
If the plugin requires login from the user at the time when they use it, then these functions can be used.

====print_login====
Returns an array of the elements required in the login form. If no login form is required, then the default implementation of this will redirect to the files list. If $this->options['ajax'] is not set, then an HTML-snippet with the login fields (but not the form tags) should be output, instead of returning the form details.
<code php>
public function print_login() { // From repository_alfresco
if ($this->options['ajax']) {
$user_field = new stdClass();
$user_field->label = get_string('username', 'repository_alfresco').': ';
$user_field->id = 'alfresco_username';
$user_field->type = 'text';
$user_field->name = 'al_username';

$passwd_field = new stdClass();
$passwd_field->label = get_string('password', 'repository_alfresco').': ';
$passwd_field->id = 'alfresco_password';
$passwd_field->type = 'password';
$passwd_field->name = 'al_password';

$ret = array();
$ret['login'] = array($user_field, $passwd_field);
return $ret;
} else { // Non-AJAX login form - directly output the form elements
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_alfresco').'</label></td>';
echo '<td><input type="text" name="al_username" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_alfresco').'</label></td>';
echo '<td><input type="password" name="al_password" /></td></tr>';
echo '</table>';
echo '<input type="submit" value="Enter" />';
}
}
</code>
This will help to generate a form by file picker which contains user name and password input elements.

For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the '__construct' function, via $submitted = optional_param('fieldname', [defaultvalue], PARAM_INT/PARAM_TEXT).
<code php>
public function __construct($repositoryid, $context = SYSCONTEXTID, $options = array()) {
// Taken from repository_alfresco

/* Skipping code that is not relevant to user login */

$this->alfresco = new Alfresco_Repository($this->options['alfresco_url']);
$this->username = optional_param('al_username', '', PARAM_RAW);
$this->password = optional_param('al_password', '', PARAM_RAW);
try{
// deal with user logging in
if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {
$this->ticket = $this->alfresco->authenticate($this->username, $this->password);
$SESSION->{$this->sessname} = $this->ticket;
} else {
if (!empty($SESSION->{$this->sessname})) {
$this->ticket = $SESSION->{$this->sessname};
}
}
$this->user_session = $this->alfresco->createSession($this->ticket);
$this->store = new SpacesStore($this->user_session);
} catch (Exception $e) {
$this->logout();
}
$this->current_node = null;

/* Skipping code that is not relevant to user login */

}
</code>

Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.
<code php>
public function print_login(){ // Code taken from repository_boxnet
$t = $this->boxclient->getTicket();
if ($this->options['ajax']) {
$popup_btn = new stdClass();
$popup_btn->type = 'popup';
$popup_btn->url = ' https://www.box.com/api/1.0/auth/' . $t['ticket'];

$ret = array();
$ret['login'] = array($popup_btn);
return $ret;
} else {
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_boxnet').'</label></td>';
echo '<td><input type="text" name="boxusername" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_boxnet').'</label></td>';
echo '<td><input type="password" name="boxpassword" /></td></tr>';
echo '<input type="hidden" name="ticket" value="'.$t['ticket'].'" />';
echo '</table>';
echo '<input type="submit" value="'.get_string('enter', 'repository').'" />';
}
}
</code>

====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.
<code php>
public function check_login() { // Taken from repository_alfresco
global $SESSION;
return !empty($SESSION->{$this->sessname});
}
</code>
====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. After this the code should return something suitable to display to the user (usually the results of calling $this->print_login() ):
<code php>
public function logout() { // Taken from repository_alfresco
global $SESSION;
unset($SESSION->{$this->sessname});
return $this->print_login();
}
</code>

===Transferring files to Moodle (optional)===
These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.

====get_file_reference($source)====
Rarely does anything other than return the $source param (the default action if not overridden), but takes the 'source' reference from the browser (originally specified in the list returned by 'get_listing') and makes sure it is ready to be passed on to the 'get_file' or 'get_file_by_reference' functions (below).

====get_file($url, $filename = "")====
For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:
* path - the local path where the file was saved
* url - the $url param passed into the function

<code php>
public function get_file($url, $filename = '') {
// Default implementation from the base 'repository' class
$path = $this->prepare_file($filename); // Generate a unique temporary filename
$c = new curl;
$result = $c->download_one($url, null, array('filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT));
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>
<code php>
public function get_file($reference, $filename = '') {
// Slightly extended version taken from repository_equella
global $USER;
// Extract the details saved in the 'source' param by
// repository/equella/callback.php (now in the $reference paramater)
$ref = @unserialize(base64_decode($reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}
$path = $this->prepare_file($filename);
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie'=>$cookiepathname));
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT));
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>

====get_link($url)====
Used with FILE_EXTERNAL to convert a reference (from 'get_file_reference', but ultimately from the output of 'get_listing') into a URL that can be used directly by the end-user's browser. Usually just returns the original $url, but may need further transformation based on the internal implementation of the repository plugin.

====get_file_source_info($source) (2.3+)====
Takes the 'source' field from 'get_listing' (as returned by the user's browser) and 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.

===Search functions (optional)===

====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

<code php>

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;
}
}
</code>

====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_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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T12:34:05Z

Davosmith: /* get_file($url, $filename = ) */

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===User login (optional)===
If the plugin requires login from the user at the time when they use it, then these functions can be used.

====print_login====
Returns an array of the elements required in the login form. If no login form is required, then the default implementation of this will redirect to the files list. If $this->options['ajax'] is not set, then an HTML-snippet with the login fields (but not the form tags) should be output, instead of returning the form details.
<code php>
public function print_login() { // From repository_alfresco
if ($this->options['ajax']) {
$user_field = new stdClass();
$user_field->label = get_string('username', 'repository_alfresco').': ';
$user_field->id = 'alfresco_username';
$user_field->type = 'text';
$user_field->name = 'al_username';

$passwd_field = new stdClass();
$passwd_field->label = get_string('password', 'repository_alfresco').': ';
$passwd_field->id = 'alfresco_password';
$passwd_field->type = 'password';
$passwd_field->name = 'al_password';

$ret = array();
$ret['login'] = array($user_field, $passwd_field);
return $ret;
} else { // Non-AJAX login form - directly output the form elements
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_alfresco').'</label></td>';
echo '<td><input type="text" name="al_username" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_alfresco').'</label></td>';
echo '<td><input type="password" name="al_password" /></td></tr>';
echo '</table>';
echo '<input type="submit" value="Enter" />';
}
}
</code>
This will help to generate a form by file picker which contains user name and password input elements.

For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the '__construct' function, via $submitted = optional_param('fieldname', [defaultvalue], PARAM_INT/PARAM_TEXT).
<code php>
public function __construct($repositoryid, $context = SYSCONTEXTID, $options = array()) {
// Taken from repository_alfresco

/* Skipping code that is not relevant to user login */

$this->alfresco = new Alfresco_Repository($this->options['alfresco_url']);
$this->username = optional_param('al_username', '', PARAM_RAW);
$this->password = optional_param('al_password', '', PARAM_RAW);
try{
// deal with user logging in
if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {
$this->ticket = $this->alfresco->authenticate($this->username, $this->password);
$SESSION->{$this->sessname} = $this->ticket;
} else {
if (!empty($SESSION->{$this->sessname})) {
$this->ticket = $SESSION->{$this->sessname};
}
}
$this->user_session = $this->alfresco->createSession($this->ticket);
$this->store = new SpacesStore($this->user_session);
} catch (Exception $e) {
$this->logout();
}
$this->current_node = null;

/* Skipping code that is not relevant to user login */

}
</code>

Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.
<code php>
public function print_login(){ // Code taken from repository_boxnet
$t = $this->boxclient->getTicket();
if ($this->options['ajax']) {
$popup_btn = new stdClass();
$popup_btn->type = 'popup';
$popup_btn->url = ' https://www.box.com/api/1.0/auth/' . $t['ticket'];

$ret = array();
$ret['login'] = array($popup_btn);
return $ret;
} else {
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_boxnet').'</label></td>';
echo '<td><input type="text" name="boxusername" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_boxnet').'</label></td>';
echo '<td><input type="password" name="boxpassword" /></td></tr>';
echo '<input type="hidden" name="ticket" value="'.$t['ticket'].'" />';
echo '</table>';
echo '<input type="submit" value="'.get_string('enter', 'repository').'" />';
}
}
</code>

====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.
<code php>
public function check_login() { // Taken from repository_alfresco
global $SESSION;
return !empty($SESSION->{$this->sessname});
}
</code>
====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. After this the code should return something suitable to display to the user (usually the results of calling $this->print_login() ):
<code php>
public function logout() { // Taken from repository_alfresco
global $SESSION;
unset($SESSION->{$this->sessname});
return $this->print_login();
}
</code>

===Transferring files to Moodle (optional)===
These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.

====get_file_reference($source)====
Rarely does anything other than return the $source param (the default action if not overridden), but takes the 'source' reference from the browser (originally specified in the list returned by 'get_listing') and makes sure it is ready to be passed on to the 'get_file' or 'get_file_by_reference' functions (below).

====get_file($url, $filename = "")====
For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:
* path - the local path where the file was saved
* url - the $url param passed into the function

<code php>
public function get_file($url, $filename = '') {
// Default implementation from the base 'repository' class
$path = $this->prepare_file($filename); // Generate a unique temporary filename
$c = new curl;
$result = $c->download_one($url, null, array('filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT));
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>
<code php>
public function get_file($reference, $filename = '') {
// Slightly extended version taken from repository_equella
global $USER;
// Extract the details saved in the 'source' param by
// repository/equella/callback.php (now in the $reference paramater)
$ref = @unserialize(base64_decode($reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}
$path = $this->prepare_file($filename);
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie'=>$cookiepathname));
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT));
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>

====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_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

<code php>

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;
}
}
</code>

====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_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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T12:33:30Z

Davosmith: /* Functions you can override */

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===User login (optional)===
If the plugin requires login from the user at the time when they use it, then these functions can be used.

====print_login====
Returns an array of the elements required in the login form. If no login form is required, then the default implementation of this will redirect to the files list. If $this->options['ajax'] is not set, then an HTML-snippet with the login fields (but not the form tags) should be output, instead of returning the form details.
<code php>
public function print_login() { // From repository_alfresco
if ($this->options['ajax']) {
$user_field = new stdClass();
$user_field->label = get_string('username', 'repository_alfresco').': ';
$user_field->id = 'alfresco_username';
$user_field->type = 'text';
$user_field->name = 'al_username';

$passwd_field = new stdClass();
$passwd_field->label = get_string('password', 'repository_alfresco').': ';
$passwd_field->id = 'alfresco_password';
$passwd_field->type = 'password';
$passwd_field->name = 'al_password';

$ret = array();
$ret['login'] = array($user_field, $passwd_field);
return $ret;
} else { // Non-AJAX login form - directly output the form elements
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_alfresco').'</label></td>';
echo '<td><input type="text" name="al_username" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_alfresco').'</label></td>';
echo '<td><input type="password" name="al_password" /></td></tr>';
echo '</table>';
echo '<input type="submit" value="Enter" />';
}
}
</code>
This will help to generate a form by file picker which contains user name and password input elements.

For plugins that do not fully process the login via a popup window, the submitted details can be retrieved, from within the '__construct' function, via $submitted = optional_param('fieldname', [defaultvalue], PARAM_INT/PARAM_TEXT).
<code php>
public function __construct($repositoryid, $context = SYSCONTEXTID, $options = array()) {
// Taken from repository_alfresco

/* Skipping code that is not relevant to user login */

$this->alfresco = new Alfresco_Repository($this->options['alfresco_url']);
$this->username = optional_param('al_username', '', PARAM_RAW);
$this->password = optional_param('al_password', '', PARAM_RAW);
try{
// deal with user logging in
if (empty($SESSION->{$this->sessname}) && !empty($this->username) && !empty($this->password)) {
$this->ticket = $this->alfresco->authenticate($this->username, $this->password);
$SESSION->{$this->sessname} = $this->ticket;
} else {
if (!empty($SESSION->{$this->sessname})) {
$this->ticket = $SESSION->{$this->sessname};
}
}
$this->user_session = $this->alfresco->createSession($this->ticket);
$this->store = new SpacesStore($this->user_session);
} catch (Exception $e) {
$this->logout();
}
$this->current_node = null;

/* Skipping code that is not relevant to user login */

}
</code>

Many types include a single element of type 'popup' with the param 'url' pointing at the URL used to authenticate the repo instance.
<code php>
public function print_login(){ // Code taken from repository_boxnet
$t = $this->boxclient->getTicket();
if ($this->options['ajax']) {
$popup_btn = new stdClass();
$popup_btn->type = 'popup';
$popup_btn->url = ' https://www.box.com/api/1.0/auth/' . $t['ticket'];

$ret = array();
$ret['login'] = array($popup_btn);
return $ret;
} else {
echo '<table>';
echo '<tr><td><label>'.get_string('username', 'repository_boxnet').'</label></td>';
echo '<td><input type="text" name="boxusername" /></td></tr>';
echo '<tr><td><label>'.get_string('password', 'repository_boxnet').'</label></td>';
echo '<td><input type="password" name="boxpassword" /></td></tr>';
echo '<input type="hidden" name="ticket" value="'.$t['ticket'].'" />';
echo '</table>';
echo '<input type="submit" value="'.get_string('enter', 'repository').'" />';
}
}
</code>

====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.
<code php>
public function check_login() { // Taken from repository_alfresco
global $SESSION;
return !empty($SESSION->{$this->sessname});
}
</code>
====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. After this the code should return something suitable to display to the user (usually the results of calling $this->print_login() ):
<code php>
public function logout() { // Taken from repository_alfresco
global $SESSION;
unset($SESSION->{$this->sessname});
return $this->print_login();
}
</code>

===Transferring files to Moodle (optional)===
These functions all relate to transferring the files into Moodle, once they have been chosen in the filepicker. All of them are optional and have default implementations which are often suitable to use as they are.

====get_file_reference($source)====
Rarely does anything other than return the $source param (the default action if not overridden), but takes the 'source' reference from the browser (originally specified in the list returned by 'get_listing') and makes sure it is ready to be passed on to the 'get_file' or 'get_file_by_reference' functions (below).

====get_file($url, $filename = '')====
For FILE_INTERNAL or FILE_REFERENCE this function is called at the point when the user has clicked on the file and then on 'select this file' to add it to the filemanager / editor element. It does the actual transfer of the file from the repository and onto the Moodle server. The default implementation is to download the $url via CURL. The $url parameter is the $reference returned by get_file_reference (above, but usually the same as the 'source' returned by 'get_listing'). The $filename should usually be processed by $path = $this->prepare_file($filename), giving the full 'path' where the file should be saved locally. This function then returns an array, containing:
* path - the local path where the file was saved
* url - the $url param passed into the function

<code php>
public function get_file($url, $filename = '') {
// Default implementation from the base 'repository' class
$path = $this->prepare_file($filename); // Generate a unique temporary filename
$c = new curl;
$result = $c->download_one($url, null, array('filepath' => $path, 'timeout' => self::GETFILE_TIMEOUT));
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>
<code php>
public function get_file($reference, $filename = '') {
// Slightly extended version taken from repository_equella
global $USER;
// Extract the details saved in the 'source' param by
// repository/equella/callback.php (now in the $reference paramater)
$ref = @unserialize(base64_decode($reference));
if (!isset($ref->url) || !($url = $this->appendtoken($ref->url))) {
// Occurs when the user isn't known..
return null;
}
$path = $this->prepare_file($filename);
$cookiepathname = $this->prepare_file($USER->id. '_'. uniqid('', true). '.cookie');
$c = new curl(array('cookie'=>$cookiepathname));
$result = $c->download_one($url, null, array('filepath' => $path, 'followlocation' => true, 'timeout' => self::GETFILE_TIMEOUT));
// Delete cookie jar.
if (file_exists($cookiepathname)) {
unlink($cookiepathname);
}
if ($result !== true) {
throw new moodle_exception('errorwhiledownload', 'repository', '', $result);
}
return array('path'=>$path, 'url'=>$url);
}
</code>

====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_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

<code php>

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;
}
}
</code>

====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_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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins embedding external file chooser

2012-12-05T12:08:30Z

Davosmith: /* updating the filepicker */

{{Repository plugins}}
By making use of the 'object' tag within the return of the 'get_listing' function, [[Repository plugins]] are able to embed an external file chooser within the repository panel. This allows for more customisation of the interface, than is allowed by simply returning a list of the available files.
The Equella plugin is an example of doing this.

==get_listing==
The returned array should return an 'object' element, containing the following:
* type - a string with the mime type of the item to display (e.g. 'text/html', 'application/x-shockwave-flash')
* url - a string with the website address to embed in the object

This will replace the usual filepicker list of files with an OBJECT html tag:
<code html4strict>
<object type="[type]" src="[url]" />
</code>

An example of generating this can be found in the Equella plugin:
<code php>
public function get_listing($path = null, $page = null) {
global $COURSE;
$callbackurl = new moodle_url('/repository/equella/callback.php', array('repo_id'=>$this->id));
$mimetypesstr = '';
$restrict = '';
if (!empty($this->mimetypes)) {
$mimetypesstr = '&mimeTypes=' . implode(',', $this->mimetypes);
// We're restricting to a mime type, so we always restrict to selecting resources only.
$restrict = '&attachmentonly=true';
} else if ($this->get_option('equella_select_restriction') != 'none') {
// The option value matches the EQUELLA paramter name.
$restrict = '&' . $this->get_option('equella_select_restriction') . '=true';
}
$url = $this->get_option('equella_url')
. '?method=lms'
. '&returnurl='.urlencode($callbackurl)
. '&returnprefix=tle'
. '&template=standard'
. '&token='.urlencode($this->getssotoken('write'))
. '&courseId='.urlencode($COURSE->idnumber)
. '&courseCode='.urlencode($COURSE->shortname)
. '&action=searchThin'
. '&forcePost=true'
. '&cancelDisabled=true'
. '&attachmentUuidUrls=true'
. '&options='.urlencode($this->get_option('equella_options') . $mimetypesstr)
. $restrict;
$list = array();
$list['object'] = array();
$list['object']['type'] = 'text/html';
$list['object']['src'] = $url;
$list['nologin'] = true;
$list['nosearch'] = true;
$list['norefresh'] = true;
return $list;
}
</code>
Note particularly the object param with the '''type''' and '''src''' elements and the presence of the '''callbackurl''' in the parameters passed to Equella. This is covered in more detail in the section below.

==updating the filepicker==
When the Equella file chooser has finished working, it then needs to update the Moodle filepicker with the details of the chosen file. It does this by redirecting the OBJECT to the '''callbackurl''' specified in the original ''url'' parameters.
This callback script (which, in the case of the Equella respository type, points to repository/equella/callback.php) extracts the details of the file returned and then outputs a small bit of javascript to update the filepicker:
<code php>
require_once(dirname(dirname(dirname(__FILE__))).'/config.php');

// Extract and decode the return value
$json = required_param('tlelinks', PARAM_RAW);
require_login();
$decodedinfo = json_decode($json);
$info = array_pop($decodedinfo);
$url = '';
if (isset($info->url)) {
$url = s(clean_param($info->url, PARAM_URL));
}

/* Omitted the extracting and cleaning of the other parameters - filename, author, etc. */

$source = base64_encode(serialize((object)array('url'=>$url,'filename'=>$filename)));

// Generate some javascript to update the filepicker with the details of the file selected
$js =<<<EOD
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<script type="text/javascript">
window.onload = function() {
var resource = {};
resource.title = "$filename";
resource.source = "$source";
resource.thumbnail = '$thumbnail';
resource.author = "$author";
resource.license = "$license";
parent.M.core_filepicker.select_file(resource);
}
</script>
</head>
<body><noscript></noscript></body>
</html>
EOD;

// Output the generated javascript
header('Content-Type: text/html; charset=utf-8');
die($js);
</code>
After this, the rest of the repository API functions (e.g. get_file) can operate as usual on the '''source''' returned to the filepicker.

==See also==

*[[Repository plugins]]

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins embedding external file chooser

2012-12-05T12:00:45Z

Davosmith:

Repository plugins embedding external file chooser

2012-12-05T12:00:23Z

Davosmith: /* updating the filepicker */

Repository plugins embedding external file chooser

2012-12-05T11:57:53Z

Davosmith: /* get_listing */

Repository plugins embedding external file chooser

2012-12-05T11:57:40Z

Davosmith: /* get_listing */

Repository plugins embedding external file chooser

2012-12-05T11:57:23Z

Davosmith: /* get_listing */

Repository plugins

2012-12-05T11:48:34Z

Davosmith: /* Database Tables */

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===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.
<code php>
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;
}
}
</code>
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

<code php>

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;
}
}
</code>

====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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins database

2012-12-05T11:48:26Z

Davosmith:

{{Repository plugins}}
== repository ==

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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 ==

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''instanceid'''
|int(int)
|
|

|-
|'''name'''
|varchar(255)
|
|

|-
|value
|Text
|
|
|}

Repository plugins database

2012-12-05T11:48:02Z

Davosmith: Created page with "== repository == {| border="1" cellpadding="2" cellspacing="0" |'''Field''' |'''Type''' |'''Default''' |'''Info''' |- |'''id''' |int(10) | |autoincrementing |- |'''type''..."

== repository ==

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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 ==

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''instanceid'''
|int(int)
|
|

|-
|'''name'''
|varchar(255)
|
|

|-
|value
|Text
|
|
|}

Template:Repository plugins

2012-12-05T11:47:17Z

Davosmith:

<div class="sideblock right" style="width: 16em;">
<div class="header">Repository plugins</div>
<div class="content">
* [[Repository plugins]]
* [[Repository plugin files]]
* [[Repository plugins embedding external file chooser|External file chooser]]
* [[Repository plugins database|Database tables]]
</div>
</div>

Repository plugin files

2012-12-05T11:45:12Z

Davosmith:

{{Repository plugins}}
This is an overview of the files that are found within [[Repository plugins]].
* /repository/myplugin/'''lib.php''' - this contains the core functionality for your plugin. Within it you must define a class:
<code php>
class repository_myplugin extends repository {
// See [[Repository plugins]] for a list of functions to override in here
}
</code>
* /repository/myplugin/'''pix/icon.png''' - an icon to display in the file picker (16x16)
* /repository/myplugin/'''[[version.php]]''' - contains the current version number of the plugin and other important details ( https://docs.moodle.org/dev/version.php )
<code php>
defined('MOODLE_INTERNAL') || die();
$plugin->version = 2012061700; //The current plugin version (Date: YYYYMMDDXX)
$plugin->requires = 2012061700; //Requires this Moodle version
$plugin->component = 'repository_myplugin'; //Full name of the plugin (used for diagnostics)
$plugin->cron = 0; // How often to run automatic updates (0 to disable)
$plugin->release = 'Human-readable version number';
</code>
* /repository/myplugin/'''lang/en/repository_myplugin.php''' - contains the English language strings for display by your plugin. As a minimum, this must include:
<code php>
defined('MOODLE_INTERNAL') || die();
$string['configplugin'] = 'Configuration for my plugin repository';
$string['pluginname'] = 'My plugin repository';
$string['pluginname_help'] = 'A few more details about my repository';
</code>
* /repository/myplugin/'''db/access.php''' - defines any user capabilities related to the plugin. A basic access.php file will look like this:
<code php>
defined('MOODLE_INTERNAL') || die();
$capabilities = array(
'repository/myplugin:view' => array(
'captype' => 'read',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => array(
'user' => CAP_ALLOW
)
)
);
</code>

Once the capabilities have been defined, it is good practice to add a language string for them to the '''lang/en/repository_myplugin.php''' file:
<code php>
$string['myplugin:view'] = 'View the myplugin repository';
</code>

==See also==

*[[Repository plugins]]

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins embedding external file chooser

2012-12-05T11:43:45Z

Davosmith:

Repository plugin files

2012-12-05T11:43:12Z

Davosmith:

{{Repository plugins}}
This is an overview of the files that are found within [[Repository plugins]].
* /repository/myplugin/'''lib.php''' - this contains the core functionality for your plugin. Within it you must define a class:
<code php>
class repository_myplugin extends repository {
// See [[Repository plugins]] for a list of functions to override in here
}
</code>
* /repository/myplugin/'''pix/icon.png''' - an icon to display in the file picker (16x16)
* /repository/myplugin/'''[[version.php]]''' - contains the current version number of the plugin and other important details ( https://docs.moodle.org/dev/version.php )
<code php>
defined('MOODLE_INTERNAL') || die();
$plugin->version = 2012061700; //The current plugin version (Date: YYYYMMDDXX)
$plugin->requires = 2012061700; //Requires this Moodle version
$plugin->component = 'repository_myplugin'; //Full name of the plugin (used for diagnostics)
$plugin->cron = 0; // How often to run automatic updates (0 to disable)
$plugin->release = 'Human-readable version number';
</code>
* /repository/myplugin/'''lang/en/repository_myplugin.php''' - contains the English language strings for display by your plugin. As a minimum, this must include:
<code php>
defined('MOODLE_INTERNAL') || die();
$string['pluginname'] = 'My plugin repository';
$string['configplugin'] = 'Configuration for my plugin repository';
</code>
* /repository/myplugin/'''db/access.php''' - defines any user capabilities related to the plugin. A basic access.php file will look like this:
<code php>
defined('MOODLE_INTERNAL') || die();
$capabilities = array(
'repository/myplugin:view' => array(
'captype' => 'read',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => array(
'user' => CAP_ALLOW
)
)
);
</code>

Once the capabilities have been defined, it is good practice to add a language string for them to the '''lang/en/repository_myplugin.php''' file:
<code php>
$string['myplugin:view'] = 'View the myplugin repository';
</code>

==See also==

*[[Repository plugins]]

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T11:42:49Z

Davosmith:

{{Repository plugins}}
== 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
# Administration - You can customise the way administrators and users can configure their repositories.
# File picker integration - The core of your plugin, it will manage communication between Moodle and the repository service, and also the file picker display.
# I18n - Internationalization should be done at the same time as you're writing the other parts.

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===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.
<code php>
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;
}
}
</code>
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

<code php>

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;
}
}
</code>

====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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

== Database Tables==

=== repository ===

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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 ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''instanceid'''
|int(int)
|
|

|-
|'''name'''
|varchar(255)
|
|

|-
|value
|Text
|
|
|}

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Template:Repository plugins

2012-12-05T11:42:17Z

Davosmith: Created page with "<div class="sideblock right" style="width: 16em;"> <div class="header">Repository plugins</div> <div class="content"> * Repository plugins * Repository plugin files * [[R..."

Repository plugins

2012-12-05T11:11:26Z

Davosmith: /* Administration APIs */

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

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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.

===Example of using the settings===

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:

<code php>
<?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 {
}
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===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.
<code php>
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;
}
}
</code>
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

<code php>

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;
}
}
</code>

====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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

== Database Tables==

=== repository ===

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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 ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''instanceid'''
|int(int)
|
|

|-
|'''name'''
|varchar(255)
|
|

|-
|value
|Text
|
|
|}

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins embedding external file chooser

2012-12-05T11:06:30Z

Davosmith: Created page with "By making use of the 'object' tag within the return of the 'get_listing' function, Repository plugins are able to embed an external file chooser within the repository panel. ..."

By making use of the 'object' tag within the return of the 'get_listing' function, [[Repository plugins]] are able to embed an external file chooser within the repository panel. This allows for more customisation of the interface, than is allowed by simply returning a list of the available files.
The Equella plugin is an example of doing this.

=get_listing=
''TODO: complete this''

=updating the filepicker=
''TODO: complete this''

==See also==

*[[Repository plugins]]

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T11:01:23Z

Davosmith: /* Functions you *MUST* override */

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

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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:

<code php>
<?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 {
}
?>
</code>

===Example of using the settings===

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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===

These functions cover the basics of initialising your plugin each time the repository is accessed and listing the files available to the user from within the plugin.

====__construct($respoitoryid, $context=SYSCONTEXTID, $options=array(), $readonly=0)====
Should be overridden to do any initialisation required by the repository, including:
* logging in via optional_param, if required - see 'print_login', below
* getting any options from the database

The possible items in the $options array are:
* 'ajax' - bool, true if the user is using the AJAX filepicker
* 'mimetypes' - array of accepted mime types, or '*' for all types

Calling parent::__construct($repositoryid, $context, $options, $readonly); is essential and will set up various required member variables:
* $this->id - the repository instance id (the ID of the entry in mdl_repository_instances)
* $this->context - the context in which the repository instance can be found
* $this->instance - the repository instance record (from mdl_repository_instances)
* $this->readonly - whether or not the settings can be changed
* $this->options - the above options, combined with the settings saved in the database
* $this->name - as specified by $this->get_name()
* $this->returntypes - as specified by $this->supported_returntypes()

====get_listing($path="", $page="")====
This function will return a list of files to be displayed to the user, the list must be a array like this:
<code php>
$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())
)
);
</code>
Amongst other details, this returns a '''title''' for each file (to be displayed in the filepicker) and the '''source''' for the file (which will be included in the request to 'download' the file into Moodle or to generate a link to the file). Directories return a '''children''' value, which is either an empty array (if 'dynload' is specified) or an array of the files and directories contained within it.

'''The full specification of list element:'''
<code php>
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
)
),
)
// The 'object' tag can be used to embed an external web page or application within the filepicker
'object' => array(
'type' => (string) e.g. 'text/html', 'application/x-shockwave-flash'
'url' => (string) the website address to embed in the object
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log Alfresco] plug-in

The use of the '''object''' tag, instead of returning a ''list'' of files, allows you to embed an external file chooser within the repository panel. See [[Repository plugins embedding external file chooser]] for details about how to do this.

===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.
<code php>
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;
}
}
</code>
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

<code php>

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;
}
}
</code>

====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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

== Database Tables==

=== repository ===

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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 ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''instanceid'''
|int(int)
|
|

|-
|'''name'''
|varchar(255)
|
|

|-
|value
|Text
|
|
|}

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T10:35:14Z

Davosmith: /* plugin_init() */

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

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
Optional. 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:

<code php>
<?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 {
}
?>
</code>

===Example of using the settings===

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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:
# Get options from database
# 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:
<code php>
$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())
)
);
</code>
'''The full specification of list element:'''
<code php>
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
)
),
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log 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.
<code php>
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;
}
}
</code>
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

<code php>

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;
}
}
</code>

====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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

== Database Tables==

=== repository ===

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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 ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''instanceid'''
|int(int)
|
|

|-
|'''name'''
|varchar(255)
|
|

|-
|value
|Text
|
|
|}

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T10:34:39Z

Davosmith: /* plugin_init() */

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

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
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:

<code php>
<?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 {
}
?>
</code>

===Example of using the settings===

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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:
# Get options from database
# 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:
<code php>
$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())
)
);
</code>
'''The full specification of list element:'''
<code php>
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
)
),
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log 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.
<code php>
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;
}
}
</code>
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

<code php>

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;
}
}
</code>

====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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

== Database Tables==

=== repository ===

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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 ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''instanceid'''
|int(int)
|
|

|-
|'''name'''
|varchar(255)
|
|

|-
|value
|Text
|
|
|}

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T10:33:32Z

Davosmith: /* Instance settings */

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

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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). All of these are optional, without them, the instance settings form will only contain a single 'name' field.

==== get_instance_option_names()====
''This function must be declared static''<br>
Optional. 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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====instance_config_form($mform)====
Optional. 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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

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

Parent function does nothing.

====instance_form_validation($mform, $data, $errors)====
Optional. 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:
<code php>
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;
}
</code>

====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''<br>
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:

<code php>
<?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 {
}
?>
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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:
# Get options from database
# 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:
<code php>
$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())
)
);
</code>
'''The full specification of list element:'''
<code php>
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
)
),
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log 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.
<code php>
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;
}
}
</code>
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

<code php>

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;
}
}
</code>

====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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

== Database Tables==

=== repository ===

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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 ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''instanceid'''
|int(int)
|
|

|-
|'''name'''
|varchar(255)
|
|

|-
|value
|Text
|
|
|}

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T10:32:40Z

Davosmith: /* Global settings */

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

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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:
<code php>
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);
}
</code>

====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:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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''<br>
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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

''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:
<code php>
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;
}
</code>

====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''<br>
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:

<code php>
<?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 {
}
?>
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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:
# Get options from database
# 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:
<code php>
$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())
)
);
</code>
'''The full specification of list element:'''
<code php>
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
)
),
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log 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.
<code php>
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;
}
}
</code>
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

<code php>

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;
}
}
</code>

====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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

== Database Tables==

=== repository ===

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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 ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''instanceid'''
|int(int)
|
|

|-
|'''name'''
|varchar(255)
|
|

|-
|value
|Text
|
|
|}

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T10:31:38Z

Davosmith: /* Administration APIs */ Rearranged and expanded the explanations slightly

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

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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).
<code php>
function supported_returntypes() {
return FILE_REFERENCE|FILE_INTERNAL|FILE_EXTERNAL;
}
</code>

====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') )
<code php>
function supported_filetypes() {
//return '*';
//return array('image/gif', 'image/jpeg', 'image/png');
return array('web_image');
}
</code>
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''<br>
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:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====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.

For example, to display the standard repository plugin settings along with the custom ones use:
<code php>
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);
}
</code>

====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.

With the example above, this function may look like:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

===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''<br>
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.
<code php>
public static function get_instance_option_names() {
return array('fs_path'); // From repository_filesystem
}
</code>

====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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

''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:
<code php>
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;
}
</code>

====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''<br>
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:

<code php>
<?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 {
}
?>
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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:
# Get options from database
# 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:
<code php>
$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())
)
);
</code>
'''The full specification of list element:'''
<code php>
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
)
),
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log 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.
<code php>
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;
}
}
</code>
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

<code php>

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;
}
}
</code>

====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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

== Database Tables==

=== repository ===

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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 ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''instanceid'''
|int(int)
|
|

|-
|'''name'''
|varchar(255)
|
|

|-
|value
|Text
|
|
|}

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugin files

2012-12-05T10:07:37Z

Davosmith:

This is an overview of the files that are found within [[Repository plugins]].
* /repository/myplugin/'''lib.php''' - this contains the core functionality for your plugin. Within it you must define a class:
<code php>
class repository_myplugin extends repository {
// See [[Repository plugins]] for a list of functions to override in here
}
</code>
* /repository/myplugin/'''pix/icon.png''' - an icon to display in the file picker (16x16)
* /repository/myplugin/'''[[version.php]]''' - contains the current version number of the plugin and other important details ( https://docs.moodle.org/dev/version.php )
<code php>
defined('MOODLE_INTERNAL') || die();
$plugin->version = 2012061700; //The current plugin version (Date: YYYYMMDDXX)
$plugin->requires = 2012061700; //Requires this Moodle version
$plugin->component = 'repository_myplugin'; //Full name of the plugin (used for diagnostics)
$plugin->cron = 0; // How often to run automatic updates (0 to disable)
$plugin->release = 'Human-readable version number';
</code>
* /repository/myplugin/'''lang/en/repository_myplugin.php''' - contains the English language strings for display by your plugin. As a minimum, this must include:
<code php>
defined('MOODLE_INTERNAL') || die();
$string['pluginname'] = 'My plugin repository';
$string['configplugin'] = 'Configuration for my plugin repository';
</code>
* /repository/myplugin/'''db/access.php''' - defines any user capabilities related to the plugin. A basic access.php file will look like this:
<code php>
defined('MOODLE_INTERNAL') || die();
$capabilities = array(
'repository/myplugin:view' => array(
'captype' => 'read',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => array(
'user' => CAP_ALLOW
)
)
);
</code>

Once the capabilities have been defined, it is good practice to add a language string for them to the '''lang/en/repository_myplugin.php''' file:
<code php>
$string['myplugin:view'] = 'View the myplugin repository';
</code>

==See also==

*[[Repository plugins]]

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugins

2012-12-05T10:07:24Z

Davosmith:

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

== History ==

Repository plugins exists from 2.0

== Example ==
*[[Box.net Repository Plugin|Box.net Repository Plugin]]
*[[Flickr Repository Plugin|Flickr Repository Plugin]]
*[[Moodle Repository Plugin|Remote Moodle Repository Plugin]]

== Template ==
There is a template available in [https://github.com/dongsheng/moodle-repository_demo Dongsheng Cai's github]

==Creating new repository plugin==
# Create a folder for your plugin in ''/repository/'' e.g. ''/repository/myplugin''
# 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''
# Declare class '''repository_myplugin extends repository''' in your lib.php
# In your repository_myplugin class overwrite function get_listing() to '''return array('list' => array());'''
# Add at least strings '''$string['pluginname']''' and '''$string['configplugin']''' to your language file
# Add capability 'repository/myplugin:view' to your access.php file
# Create install and upgrade scripts (optional or you can do it later)
# Login as admin on your website and run upgrade
# 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==

===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''<br>
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:
<code php>
$mform->addElement('text', 'email_address', get_string('emailaddress', 'repository_flickr_public'));
$mform->addRule('email_address', $strrequired, 'required', null, 'client');
</code>

''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. For instance:
<code php>
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;
}
</code>

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

For example:
<code php>
public static function get_type_option_names() {
return array_merge(parent::get_type_option_names(), array('rootpath'));
}
</code>

====type_config_form(&$mform)====
This is for modifying the Moodle form displaying the plugin settings.

For example, to display the standard repository plugin settings along with the custom ones use:
<code php>
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);
}
</code>

====type_form_validation($mform, $data, $errors)====
Use this function if you need to validate some variables submitted by plugin settings form. Push the items to $error array in the format ("fieldname" => "errormessage") to have them highlighted in the form.

With the example above, this function may look like:
<code php>
public static function type_form_validation($mform, $data, $errors) {
if (!is_dir($data['rootpath'])) {
$errors['rootpath'] = get_string('invalidrootpath', 'repository_someplugin');
}
return $errors;
}
</code>

====plugin_init()====
''This function must be declared static''<br>
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:

<code php>
<?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 {
}
?>
</code>

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.

<code php>
//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');
}
</code>

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:
<code php>
//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');
}
</code>

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:

<code php>
//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);
}
</code>

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 [http://moodle.org/mod/forum/discuss.php?d=119961 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:
# Get options from database
# 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:
<code php>
$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())
)
);
</code>
'''The full specification of list element:'''
<code php>
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
)
),
)
)
</code>
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 [http://cvs.moodle.org/moodle/repository/alfresco/lib.php?view=log 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.
<code php>
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;
}
}
</code>
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

<code php>

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;
}
}
</code>

====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'':

<code php>
$string['pluginname'] = 'Flickr Public';
$string['configplugin'] = 'Flickr Public configuration';
$string['pluginname_help'] = 'A Flickr public repository';
</code>

== Database Tables==

=== repository ===

{| border="1" cellpadding="2" cellspacing="0"
|'''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.

{| border="1" cellpadding="2" cellspacing="0"
|'''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 ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''instanceid'''
|int(int)
|
|

|-
|'''name'''
|varchar(255)
|
|

|-
|value
|Text
|
|
|}

==See also==

*[[Plugins]]
*[[Repository_Interface_for_Moodle/Course/User| Repository Interface for Moodle/Course/User]]
*[[QA:Use Case Number Attribution| Use Case Number Attribution]]
* MDL-16543 - A list of officially supported repository plugins
* MDL-16543 - Template plugin for developers

[[Category:Repositories]]
[[Category:Plugins]]

Repository plugin files

2012-12-05T10:05:06Z

Davosmith: Created page with "This is an overview of the files that are found within Repository plugins. * /repository/myplugin/'''lib.php''' - this contains the core functionality for your plugin. Within..."

This is an overview of the files that are found within [[Repository plugins]].
* /repository/myplugin/'''lib.php''' - this contains the core functionality for your plugin. Within it you must define a class:
<code php>
class repository_myplugin extends repository {
// See [[Repository plugins]] for a list of functions to override in here
}
</code>
* /repository/myplugin/'''pix/icon.png''' - an icon to display in the file picker (16x16)
* /repository/myplugin/'''[[version.php]]''' - contains the current version number of the plugin and other important details ( https://docs.moodle.org/dev/version.php )
<code php>
defined('MOODLE_INTERNAL') || die();
$plugin->version = 2012061700; //The current plugin version (Date: YYYYMMDDXX)
$plugin->requires = 2012061700; //Requires this Moodle version
$plugin->component = 'repository_myplugin'; //Full name of the plugin (used for diagnostics)
$plugin->cron = 0; // How often to run automatic updates (0 to disable)
$plugin->release = 'Human-readable version number';
</code>
* /repository/myplugin/'''lang/en/repository_myplugin.php''' - contains the English language strings for display by your plugin. As a minimum, this must include:
<code php>
defined('MOODLE_INTERNAL') || die();
$string['pluginname'] = 'My plugin repository';
$string['configplugin'] = 'Configuration for my plugin repository';
</code>
* /repository/myplugin/'''db/access.php''' - defines any user capabilities related to the plugin. A basic access.php file will look like this:
<code php>
defined('MOODLE_INTERNAL') || die();
$capabilities = array(
'repository/myplugin:view' => array(
'captype' => 'read',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => array(
'user' => CAP_ALLOW
)
)
);
</code>

==See also==

*[[Repository plugins]]

[[Category:Repositories]]
[[Category:Plugins]]

version.php

2012-07-02T19:36:46Z

Davosmith:

This file is included in the main directory of plugin. It is compulsory for most plugin types. Even when not compulsory it is highly recommended.

It contains a number of fields, which are used during the install / upgrade process to make sure the plugin is compatible with the current Moodle install, as well as spotting whether an upgrade is needed.

The file is a standard PHP file, starting with an opening '<?php' tag and defining the following variables:

'''Note! For Activity modules replace $plugin-> with $module-> in the following example!'''

* $plugin->version = 2011051000;
** Required - the version number of your plugin in the form YYYYMMDDxx, so this example is 10th May 2011 (with 00 indicating this is the first version for that day)
* $plugin->requires = 2010112400;
** Optional - minimum version number of Moodle that this plugin requires (Moodle 1.9 = 2007101509; Moodle 2.0 = 2010112400; Moodle 2.1 = 2011070100; Moodle 2.2 = 2011120100; Moodle 2.3 = 2012062500). See [[Releases]] for a full list.
* $plugin->cron = 0;
** Optional - time interval (in seconds) between calls to the plugin's 'cron' function; set to 0 to disable the cron function calls.
** Cron support is not yet implemented for all plugins.
* $plugin->component = 'plugintype_pluginname';
** Optional - ''frankenstyle'' plugin name, strongly recommended. It is used for installation and upgrade diagnostics.
* $plugin->maturity = MATURITY_STABLE;
** Optional - how stable the plugin is: MATURITY_ALPHA, MATURITY_BETA, MATURITY_RC, MATURITY_STABLE (Moodle 2.0 and above)
* $plugin->release = '2.x (Build: 2011051000)';
** Optional - Human-readable version name
* $plugin->dependencies = array('mod_forum' => ANY_VERSION, 'mod_data' => 2010020300);
** Optional - list of other plugins that are required for this plugin to work (Moodle 2.2 and above)
** In this example, the plugin requires any version of the forum activity and version '20100020300' (or above) of the database activity

Here is a template to copy and paste:
<code php>
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* TODO
*
* @package TODO_FRANKENSTYLE
* @copyright TODO
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

defined('MOODLE_INTERNAL') || die();

$plugin->version = TODO;
$plugin->requires = TODO; // See https://docs.moodle.org/dev/Moodle_Versions
$plugin->cron = 0;
$plugin->component = 'TODO_FRANKENSTYLE';
$plugin->maturity = MATURITY_STABLE;
$plugin->release = 'TODO';

$plugin->dependencies = array(
'mod_forum' => ANY_VERSION,
'mod_data' => TODO
);
</code>

==See also==

* [[Moodle versions]]

[[Category:Plugins]]

Moodle 2.3 release notes

2012-06-26T11:01:14Z

Davosmith: /* Plugin API changes */

[[Releases]] > {{FULLPAGENAME}}

Release date: 25th June 2012

Here is [http://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%222.3%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 2.3].

Many thanks to [http://moodle.org/dev/contributions.php?version=2.3.x everyone that worked on the new features in this release], including those from [http://moodle.com/hq/team Moodle HQ], [http://www.open.ac.uk/ The Open University], [http://www.netspot.com.au/ NetSpot], [http://www.synergy-learning.com/ Synergy Learning], [http://www.luns.net.uk/ Lancaster University Network Services], [http://catalyst.net.nz/ Catalyst IT], [http://www.cvaconsulting.com/ CV&A Consulting] (funded by [http://www.esade.edu ESADE] and [http://www.il3.ub.edu IL3-UB]) and others. More details can be found below under each major feature, or look at the list of bugs fixed above.

A special thanks to our incredible ''''Integration Team'''' from Moodle HQ who worked tirelessly with all developers to review, test and help finish code for inclusion in Moodle core:

* Eloy Lafuente
* Sam Hemelryk
* Dan Poltawski
* Aparup Bannerjee

Finally, thanks to all our testers both within Moodle HQ and from the whole community, who have contributed to producing our most exciting and stable release yet!

===Requirements===

* Minimum browser: Firefox 4, Internet Explorer 8, Safari 5, Google Chrome 11, Opera 9
* Moodle upgrade: Moodle 2.2 or later (if upgrading from earlier versions, you must upgrade to 2.2 as a first step)
* Minimum DB versions: Postgres 8.3, MySQL 5.1.33 (MDL-33984), MSSQL 2005 or Oracle 10.2
* Minimum PHP version: PHP 5.3.2

===Major new features===

====Files usability====

* MDL-31907 - A nicer-looking file picker with fewer clicks.
* Images now display as true thumbnails in the file picker and file manager.
* Other files have pretty icons for most file types.
* Files view can be easily toggled between icons view or a table view with sizes and dates, or a hierarchical list view.
* You can now drag and drop files directly from your desktop straight into file areas!
* File info (eg license information, sizes, dates) can be easily edited and viewed in a popup dialogue.
* Files can be created as "aliases/shortcuts" of other files. This allows you to, for example, use a single file in your private files area multiple times in all your courses. If you update the original file then all the aliases will automatically update!
* Aliases are easily identifiable in the file manager interface.

Credits to Moodle HQ: Marina Glancy, Barbara Ramiro, Martin Dougiamas, David Mudrak, Dongsheng Cai and others.

{|
|-
| [[File:truthumbnailsiconsview.png|thumb|File picker icon view]]
| [[File:tableview.png|thumb|File picker table view]]
| [[File:hierarchicallistview.png|thumb|File picker hierarchical list view]]
|-
| [[File:popupdialogue.png|thumb|File info popup dialogue]]
| [[File:alias.png|thumb|Creating an alias]]
| [[File:shortcut1.png|thumb|Aliases are easily identifiable]]
|}
====Repository improvements====

* MDL-32117 - New [https://docs.moodle.org/23/en/EQUELLA_repository EQUELLA repository] enabling users to make aliases (shortcuts) to EQUELLA files.
* MDL-28666 - If a repository supports it then it's possible to make an alias/shortcut to a file in an external repository. If the file is updated in the repository, then this change is reflected in Moodle. The file remains under Moodle access control however, and the original URL is not usually revealed. In the 2.3 core release, this is supported by private files, server files, file system, Box.net and EQUELLA repositories.
* The repository plugin is now able to take over the whole right-hand pane of the file picker and provide it's own searching/browsing interface.
* MDL-31675 - Server files repository now available for database, forum and glossary activities.

Credits to Moodle HQ: Dongsheng Cai, Marina Glancy, Martin Dougiamas, Petr Skoda

====Improvements to course pages ====

* MDL-32476 - Courses can now choose to show sections on individual pages
* MDL-31052 - All AJAX editing on the course pages has been modernised and cleaned up (YUI3). It's on by default now too.
* MDL-31263 - Blocks can be dragged and dropped around the page (again)
* MDL-30617 - An optional new popup [https://docs.moodle.org/23/en/Course_homepage "Activity chooser"] has been added with full introduction, examples and links about each activity or resource module.
* MDL-22504 - You can now drag files straight into the course page and they will be added as resources.
* MDL-31215 - You can edit the name of any activity or resource directly on the course page without entering the settings (works particularly well with drag and drop).
* MDL-32771 - You can now add/remove sections directly from the [https://docs.moodle.org/23/en/Course_homepage course page].

Credits to: Andrew Nicols and Ruslan Kabalin (LUNS) Davo Smith (Synergy Learning), Dan Poltawski and Martin Dougiamas (Moodle HQ)

{|
| [[File:dragandrop.png|thumb|File drag and drop]]
| [[File:activity chooser.png|thumb|Activity chooser]]
|}
====Assignment module====

* MDL-26997 - Complete rewrite of the assignment module from scratch, by [http://www.netspot.com.au/ NetSpot] (Moodle Partner in Australia)
* Assignment subtypes are no longer needed. New plugins are possible for
* Old Assignment module is still installed, and works, but is not necessary

Credits to Netspot: Damyon Wiese, Raymond Wijaya, Minh-Tam Nguyen

* MDL-31731 - New [https://docs.moodle.org/23/en/Marking_guide marking guide] advanced grading method, where a teacher enters a comment per criterion and a mark up to a maximum

Credits to Catalyst IT: Dan Marsden with funding from the Lightwork team at Massey University.

====Book module====

* MDL-32709 - The most popular third-party resource module ever, [https://docs.moodle.org/23/en/Book_module Book] finally joins core. Welcome!

Credits to Petr Škoda, Moodle HQ

====Quiz module====

* MDL-3030 - More robust handling of quiz attempts that are not submitted by the deadline.
* MDL-3054 & MDL-11047 - There is now an option for teacher to force students to answer the quiz questions strictly in order. As part of this, the quiz remembers which page the student was last on, and will take them back there when they resume an attempt.

Credits to Tim Hunt, The Open University and Charles Fulton, Lafayette College

====SCORM module====

* MDL-29745 - New [https://docs.moodle.org/23/en/Using_SCORM SCORM graph report] plugin (credits to Ankit Agarwal, Moodle HQ and Dan Marsden, Catalyst IT)
* MDL-32937 - You can now drag a SCORM package straight into the course page and it will be added as SCORM activity (credits to Christopher Tombleson and Dan Marsden, Catalyst IT, and Davo Smith, Synergy Learning)

====Workshop module====

* MDL-26099 - [https://docs.moodle.org/23/en/Workshop_settings Option to make the workshop switch to the assessment phase] automatically after the submissions deadline (including automatic allocation of submissions for assessment)
* MDL-25660 - Workshop submission deadlines are shown in the calendar
* MDL-27508 - Improved support for pagination and filtering workshop submissions by group
* MDL-32638 - Workshop supports file browsing via Server files repository (including improved access control when serving submission files)

Credits to David Mudrak, Moodle HQ

====Available update notifications====

*MDL-20438 - Admins are sent [https://docs.moodle.org/23/en/Notifications notification of any updates available] for core code and for any contributed plugins installed on the site (from the [http://moodle.org/plugins plugins directory]). Admins can also check for available updates using buttons on the notifications and plugins overview pages.

Credits to David Mudrak, Moodle HQ

===Other highlights===

====Google Docs and Picasa plugins requirement====

* MDL-29857 - Due to a change in Google's service, Moodle has switched to a more secure and more user-friendly system for communicating with Google called 'OAuth 2.0'. An administrator must register their site with Google, as described in [https://docs.moodle.org/23/en/Google_OAuth_2.0_setup Google OAuth 2.0 setup] in order to obtain a client ID and secret for use in configuring all Google Docs and Picasa plugins (the Google Docs and Picasa repositories and the Google Docs and Picasa portfolios).

Credits to Dan Poltawski, Moodle HQ

====IMS Common Cartridge 1.1 Export====

* MDL-33079 - In Moodle 2.2 we introduced IMS CC import. Well, now you can also export to that format, via the normal Backup menu. Just look for the IMS CC checkbox.

====Miscellaneous====

* MDL-31121 - Option in [https://docs.moodle.org/23/en/File_module_settings file resource settings] to display file size and/or type on course page (credits to Sam Marshall, The Open University)
* MDL-32009 - Admin option for uninstalling messaging outputs and report of messaging output statuses on plugins overview page
* MDL-29941 - Admin option to enable a [https://docs.moodle.org/23/en/CSS_optimiser CSS optimiser] that analyses and refactors CSS before caching it
* MDL-24419 - [https://docs.moodle.org/23/en/Conditional_activities_settings Conditional activities setting] enabling teachers to restrict access to a course section using similar logic to Conditional Activities (with thanks to the [http://www.unsw.edu.au/ University of New South Wales] for funding and [http://www.netspot.com.au/ NetSpot] for developing this feature and Sam Marshall at the [http://www.open.ac.uk OU] for integrating it to core)
* MDL-26901 - Option to add extra fonts to the [https://docs.moodle.org/23/en/Text_editor TinyMCE HTML editor]
* MDL-31315 - When editing a form, a warning will be displayed if trying to navigate away with content edited
* MDL-33401 - Managers are now allowed the capability to edit blocks (moodle/block:edit) by default for new installs. This does not affect existing installations.
* MDL-32005 - New group and groupings ID number setting for matching groups and groupings against external systems (credits to Andrew Nicols, LUNS)
* MDL-30482 - New [https://docs.moodle.org/23/en/Capabilities/mod/glossary:view view glossary entries capability]
* MDL-31158 - New [https://docs.moodle.org/23/en/Grade_settings recover grades default setting]
* MDL-11378 - New [https://docs.moodle.org/23/en/Messaging_settings SMTP security email setting]

===Security issues===

All security issues that were fixed in 2.2.x and 2.1.x were also fixed in 2.3.

===For developers: API changes===

Abbreviated descriptions of API changes are always kept up to date in the "upgrade.txt" within each plugin area. We do this so that the information is always exactly right for the version of Moodle you are using. Changes in this release:

;Blocks: http://git.moodle.org/gw?p=moodle.git;a=blob;f=blocks/upgrade.txt;hb=master
;Course formats: http://git.moodle.org/gw?p=moodle.git;a=blob;f=course/format/upgrade.txt;hb=master
;Filters: http://git.moodle.org/gw?p=moodle.git;a=blob;f=filter/upgrade.txt;hb=master
;Activity modules: http://git.moodle.org/gw?p=moodle.git;a=blob;f=mod/upgrade.txt;hb=master
;Quiz access rules: http://git.moodle.org/gw?p=moodle.git;a=blob;f=mod/quiz/accessrule/upgrade.txt;hb=master
;Quiz reports: http://git.moodle.org/gw?p=moodle.git;a=blob;f=mod/quiz/report/upgrade.txt;hb=master
;Portfolio plugins: http://git.moodle.org/gw?p=moodle.git;a=blob;f=portfolio/upgrade.txt;hb=master
;Question behaviour plugins: http://git.moodle.org/gw?p=moodle.git;a=blob;f=question/behaviour/upgrade.txt;hb=master
;Question behaviour plugins: http://git.moodle.org/gw?p=moodle.git;a=blob;f=question/format/upgrade.txt;hb=master
;Question types: http://git.moodle.org/gw?p=moodle.git;a=blob;f=question/type/upgrade.txt;hb=master
;Repository plugins: http://git.moodle.org/gw?p=moodle.git;a=blob;f=repository/upgrade.txt;hb=master
;Themes: http://git.moodle.org/gw?p=moodle.git;a=blob;f=theme/upgrade.txt;hb=master

====Core API changes====
* MDL-31902 All xxx_get_participants() functions are removed from core
* As a part of MDL-32471, the signature of send_stored_file() has been [http://git.moodle.org/gw?p=moodle.git;a=commitdiff;h=796495fed29f12e4a81bd406558d8eeffd0e64ac modified]. The last two parameters $filename and $dontdie were replaced with a single array containing additional options for the file serving. The pluginfile callbacks in plugins are supposed to transfer these options from the caller to send_stored_file() - see the note below.
* MDL-28666 Files API changes, added ability to create file reference using file_storage::create_file_from_reference() method, update file record attributes using stored_file class
* MDL-28666 Repository API changes, added new APIs repository::get_file_reference(), repository::get_file_by_reference(), repository::get_reference_details(), repository::send_file(), the new APIs make serving files from external repository possible
* MDL-33446 Make sure that areas in your plugins where you DON'T want content to change have support for file references turned OFF. Some areas in Moodle core that do not support references are assignment submissions, workshop submissions, forum posts, and quiz essay questions - this is so that students are not able to update files from outside Moodle after any due date
* AJAX Flags: MDL-32509 and MDL-32908 The $CFG->enablecourseajax and $USER->ajax fields have been removed. The fields was not widely respected and all 'advanced javascript' should work in a progressive enhancement and accessible way. A site wide flag still exists but may be phased out in the future.

====Plugin API changes====

* As a part of MDL-32471, the API of the plugin function xyz_pluginfile() has been extended. There is a new array parameter passed to these callbacks containing additional options for the file serving. The array should be re-passed to send_stored_file(). The change is pretty trivial - see [http://git.moodle.org/gw?p=moodle.git;a=commitdiff;h=261cbbacc15ef1732a357d689908c91c15e0617a examples].
* Activity modules can now declare support for course drag and drop upload [[Implementing_Course_drag_and_drop_upload_support_in_a_module]]

====Webservice changes====
Few changes could break existing web service clients in 2.3 - untill this version we tried not to break anything. However these changes will make the client's developer life easier, so we prefered to do them now than later. Please take in consideration these improvements and retest your clients:
* [https://docs.moodle.org/dev/Errors_handling_in_web_services Error codes and Warnings]
* All text fields have an additional format field as parameter and return value (MDL-32581)
* Thanks to the increasing number of contributions, we improved our [https://docs.moodle.org/dev/How_to_contribute_a_web_service_function_to_core contributor web service guide]
* From 2.3, all web service functions integrated in master will land (when possible) in supported minor versions (e.g. 2.3.1, 2.3.2...).
* Many [http://tracker.moodle.org/browse/MDL-31253 fixes] and new [http://tracker.moodle.org/browse/MDL-29934 API functions].

====Unit tests====

We have switched completely to using [[PHPUnit]] for all our unit tests now. All existing simpletests have been rewritten, and new tests have been added.

We intend to move towards a completely unit-test-driven development methodology (where the tests are written first!) for significant new code, and we also encourage all developers to implement unit tests covering at least the core features of their code.

Moodle HQ run these tests on an automated basis for all new code submitted for integration, as well as on each weekly release.

==== Community hub changes ====
Some bug fixes and improvements in [http://tracker.moodle.org/browse/MDL-30247 core] and in the [http://tracker.moodle.org/browse/CONTRIB-3348 plugin]. Hub administrators must update their hub to the most recent version regarding CONTRIB-3646.

<noinclude>==See also==

* [https://docs.moodle.org/23/en/Category:New_features User documentation of new features in Moodle 2.3]
* [https://docs.moodle.org/23/en/Upgrading_to_Moodle_2.3 Upgrading to Moodle 2.3] - information for admins who are upgrading from earlier versions
*[[Moodle 2.2 release notes]]

[[Category:Release notes]]
[[Category:Moodle 2.3]]

[[fr:Notes de mise à jour de Moodle 2.3]]
</noinclude>

Implementing Course drag and drop upload support in a module

2012-06-26T10:59:12Z

Davosmith: Created page with "When a user drags and drops files, links or text onto a course, any activity module can register to receive this data. Note that only 'file' support is enabled by default - text ..."

When a user drags and drops files, links or text onto a course, any activity module can register to receive this data. Note that only 'file' support is enabled by default - text & URL handling needs to be enabled under the system 'experimental' features.

To support drag and drop upload, the module needs to add the following two functions to its lib.php file:

== xx_dndupload_register() ==

This should return an array declaring what types of upload it can handle (and, optionally, any extra types that are not supported as standard).

If the module wants to accept files, then it should return something like this:

<pre><nowiki>
return array('files' => array(
array('extension' => 'doc', 'message' => get_string('dosomethingwithdoc', 'mod_xx')),
array('extension' => 'pdf', 'message' => get_string('dosomethingwithpdf', 'mod_xx'))
));
</nowiki></pre>
This code declares that the particular module wants to handle files ending '.doc' or '.pdf' and also gives the text to display to the user if there is a choice of more than one module to handle that particular file type. Note setting the extension to '*' will mean this module could handle any file type.

To handle non-file types, the return should look something like this:

<pre><nowiki>
return array('types' => array(
array('identifier' => 'url', 'message' => get_string('dosomethingwithurl', 'mod_xx')),
array('identifier' => 'text/html', 'message' => get_string('dosomethingwithhtml', 'mod_xx')),
array('identifier' => 'text', 'message' => get_string('dosomethingwithtext', 'mod_xx'))
));
</nowiki></pre>
This declares that the particular module wants to handle all 3 built-in drop types (url, text/html, text) and gives the message to display in each case, if the user has a choice of more than one module to handle that particular type. Note that you can declare support for both 'files' and 'types' by including both in the returned array.

If you need to support the dropping of other types onto the course (in addition to files, text, text/html or url), you can declare the type as below:

<pre><nowiki>
return array('addtypes' => array(
array('identifier' => 'newtypename', 'datatransfertypes' => array('newtype', 'text/newtype'),
'addmessage' => get_string('addmessage', 'mod_xx'), 'namemessage' => get_string('namemessage', 'mod_xx'),
'priority' => 100)
));
</nowiki></pre>
This declares support for a new type, to be known as 'newtypename' (which is the 'identifier' you would need to put in the 'types' array in the previous section). This should be used whenever the browser declares the clipboard data includes one of the types listed in 'datatransfertypes'. Whilst the drag is in progress, the 'addmessage' will be displayed in the current course section (e.g. 'Add a new page here'). Once the drag is complete, the 'namemessage' will be displayed to the user, to get the activity name (e.g. 'What do you want to call this page?'). The priority controls the order in which types are chosen (smaller meaning earlier) - this allows, for example, the 'url' type to be chosen first even when the data could also be interpreted as 'text' type.

== xx_dndupload_handle($uploadinfo) ==

This function receives information about the current upload. It is expected to create a new instance of the module (similarly to how xx_add_instance works) and return the new instance id. If there is a problem, it should return 0 (the coursemodule will then be deleted and the user informed that there was a problem creating the activity).

The data supplied includes:
* $uploadinfo->course - the course object that the upload was dropped onto
* $uploadinfo->displayname - the name the user gave (or the name of the file, after removing the extension and replacing underscores with spaces)
* $uploadinfo->coursemodule - the ID of the coursemodule created to hold this activity
* $uploadinfo->type - the type of upload (either 'Files', or one of the 'types' identifiers listed above)
* $uploadinfo->draftitemid - the ID of the draft area that stores the file the user has uploaded (only for 'Files' type - note there will only be a single file in the area, as multi-file uploads are handled as separate AJAX calls)
* $uploadinfo->content - the raw content dropped onto the browser (only for non-file uploads)

== See also ==
Please take a look at the code for the built-in modules: resource, folder, scorm, url or page for examples of how to use these functions

[[Category:Modules]]
[[Category:Tutorial]]
[[Category:Plugins]]

Activity modules

2012-06-26T10:18:00Z

Davosmith: Add a mention of course drag and drop upload support

Activity modules reside in the '''/mod''' directory. They are the oldest type of plugins in Moodle - that's why they have this overly-generic name and also why they have a few idiosyncrasies and operate slightly differently from all the plugins that came later.

Each module is in a separate subdirectory and consists of a number of ''''mandatory elements'''' (see below) plus extra scripts unique to each module.

In the example below we will assume a module called ''''widget'''', that is stored in the ''''/mod/widget'''' directory. All functions and classes should have names starting with '''widget_'''' and any constants you define should start with ''''WIDGET_''''. (Note that activity modules are the only exception from the normal frankenstyle naming rules which would normally have required prefixes like "mod_widget_")

* ''[[mod_form.php]]'' - a form to set up or update an instance of this module
* ''[[version.php]]'' - defines some meta-info
* ''pix/icon.gif'' - a 16x16 icon for the module
* ''db/install.xml'' - defines the structure of db tables for all database types. Is used during module installation
* ''[[db/upgrade.php]]'' - defines changes in the structure of db tables. Is used during module upgrade
* ''[[db/access.php]]'' - defines module capabilities
* ''[[index.php]]'' - a page to list all instances in a course
* ''[[view.php]]'' - a page to view a particular instance
* ''[[lib.php]]'' - all functions intended to be called from OUTSIDE this activity module are here. Required functions are:
:* widget_install() - will be called during the installation of the module
:* widget_add_instance() - code to add a new instance of widget
:* widget_update_instance() - code to update an existing instance
:* widget_delete_instance() - code to delete an instance
:* widget_user_outline() - given an instance, return a summary of a user's contribution
:* widget_user_complete() - given an instance, print details of a user's contribution
:* widget_get_view_actions() / widget_get_post_actions() - Used by the participation report (course/report/participation/index.php) to classify actions in the logs table.
:* Other functions available but not required are:
:** widget_delete_course() - code to clean up anything that would be leftover after all instances are deleted
:** widget_process_options() - code to pre-process the form data from module settings
:** [[Implementing Reset course functionality in a module|widget_reset_course_form() and widget_delete_userdata()]] - used to implement [[Reset course]] feature.
:** [[Implementing Course drag and drop upload support in a module|widget_dndupload_register() and widget_dndupload_handle()]] - used to support Course drag and drop upload.
* ''backuplib.php'' and ''restorelib.php'' (optional)
* ''settings.php'' or ''settingstree.php'' - (optional) a definition of an admin settings page for this module. mod/assignment/settings.php is a good simple example. mod/quiz/settingstree.php is a more complex example.
* ''defaults.php'' - lets you easily define default values for your configuration variables. It is included by upgrade_activity_modules in lib/adminlib.php. It should define an array $defaults. These values are then loaded into the config table. Alternatively, if you set $defaults['_use_config_plugins'] to true, the values are instead loaded into the config_plugins table, which is better practice. See mod/quiz/defaults.php for an example. (This apparently only works with moodle 2.x branch.)
* ''lang/en/widget.php'' - Lastly, each module will have some language files that contain strings for that module, especially:
:* $string['pluginname'] = 'Widget';

=== IMPORTANT: ===
* When creating a new module, the new name of the module must not contain numbers or other special characters!

* You need a ''data base table'' with the same name as your module. This table must have at least three fields:
*# id
*# course
*# name

* You should also make sure that your activity module provides appropriate support for groups and meta-courses.

== See also ==

* Moodle 2.x activity module template [https://github.com/moodlehq/moodle-mod_newmodule https://github.com/moodlehq/moodle-mod_newmodule] for developing new modules.
* [[Blocks]]
* [[Backup]]
* Tracker issue [http://tracker.moodle.org/browse/CONTRIB-52 CONTRIB-52 Improvements to make NEWMODULE really useful] - including download link for new module template supporting roles, formslib etc. (unfinished)
* http://download.moodle.org/plugins16/mod/NEWMODULE.zip - new module template for versions of Moodle prior to 1.7. Please follow the README instructions inside the zip.
* [[NEWMODULE_Documentation]]

Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=66165 A new resource type: where do I put the language strings?]
*[http://moodle.org/mod/forum/discuss.php?d=65986 New Module Template Code for Moodle 1.7]
*[http://moodle.org/mod/forum/discuss.php?d=90154 LEGACY roles and capabilities]

[[Category:Modules]]
[[Category:Modules]]
[[Category:Tutorial]]
[[Category:Plugins]]

Plugin validation

2012-06-18T18:46:29Z

Davosmith: Clarified the timescales involved in manual checking.

Before a plugin can be made available via the [http://moodle.org/plugins/ Moodle Plugins directory] it has to pass both an automatic and a manual validation process. The automatic checks are repeated for each new version of the plugin that is added, however the [http://moodle.org/mod/forum/discuss.php?d=192083#p837517 manual checks are only done for the initial release]. The aim is to complete manual checks within 48 hours of first submission, but it can sometimes take longer than that, so please be patient.
=Automatic validation=

==General rules for all plugin types==
* Plugin name with [[Frankenstyle]] prefix must be unique in moodle.org/plugins. If there is another plugin with the same name you must either add new versions to this plugin (if it is yours) or rename your plugin if the names are accidentally the same. First in first served.
* The plugin must be uploaded as a single zip file
* The zip file must contain a single subfolder, named after your plugin (although the validator can also automatically rename subfolders generated by repos such as GitHub, which appear in the form 'username-moodle-pluginname-branchname')
* The subfolder must be laid out in such a way that the uploaded file could be unzipped directly into the top-level folder for that plugin type (e.g. an activity plugin called 'myplugin' should install correctly when unzipped in the Moodle /mod folder, creating a subfolder /mod/myplugin with all the standard files within it).
* The subfolder must contain a file called [[version.php]] (follow the link for more details about what should be contained within that file). See exceptions below.
* Language file must be present in lang/en/FULLNAME.php (for Moodle 2.0+) or lang/en_utf8/FULLNAME.php (for Moodle 1.9). FULLNAME is the plugin name with frankenstyle prefix. See exceptions below.
* Language file must declare either $string['modulename'] (for activity modules) or $string['filtername'] (for Filters) or $string['pluginname'] (for all other plugin types). See exceptions below.
* The names of all database tables should start with the full 'frankenstyle' plugin name. For example block_myblock, or auth_paypal. See exceptions below.
* (Recommended) the subfolder should contain a file called README.txt (the validator can automatically rename other extensions to .txt) with details about the current release of the plugin.

==Exceptions==
* version.php is NOT required (but it is always recommended) for the following plugin types:
** Themes
** Course formats
** Blocks for Moodle 1.9
** Auth for Moodle 1.9
* language file is not required for plugins for Moodle 1.9 that are not activity modules
* $string['pluginname'] is not required for plugins for Moodle 1.9 that are not activity modules
* Question types for Moodle versions <= 2.1 instead of $string['pluginname'] should declare $string[NAME] (where NAME is the name of the plugin without frankenstyle prefix). Starting from 2.2 this was fixed and $string['pluginname'] shall be used.
* database tables are allowed to skip mod_ prefix for activity modules
* database tables are allowed to have question_ prefix instead of qtype_ for Question types. This is for historical reasons, all newly developed plugins are encouraged to have qtype_ prefix.

==Additional checks for activity modules==
* $module->version defined in version.php
* $module->requires defined in version.php
* file lib.php exists
* file lib.php contains “function xxxx_add_instance”
* file lib.php contains “function xxxx_update_instance”
* file view.php exists
* file index.php exists
* db/install.xml exists
* db/upgrade.php exists
* db/access.php exists

==Checks for particular plugin types==
* Themes: file config.php exists
* Blocks: file block_xxxx.php exists
* Auth: file auth.php exists
* Course formats: file format.php exists

=Manual checks=
Before the plugin is publicly viewable a trusted reviewer will look through the code to make sure it is a valid plugin. Currently, these checks are completed by Anthony Borrow on a volunteer basis, so please bear with him if this sometimes takes a little longer than you expect. These checks include:
* The plugin installs cleanly
* It does not contain any obviously harmful code
* It is not a spam entry
* It is not a duplicate of an already uploaded plugin

=Frequently asked questions=
===Q: My code contains several components, why can't I distribute it as a single package?===
A: Moodle architecture supposes that plugins are installed independently. However you can contact the plugins database moderator and ask to add your plugins to the SET.
For Moodle 2.2 and above you can also specify in your version.php that one plugin depends on another.

[[Category:Plugins]]

Course module

2012-03-02T08:00:09Z

Davosmith: Created page with "==Summary== A course module (often abbreviated 'cm') represents each of the activities and resources found in a course. It contains information about which course and section the..."

==Summary==
A course module (often abbreviated 'cm') represents each of the activities and resources found in a course. It contains information about which course and section the activity / resource is displayed on, as well as details about the visibility, group and completion status of the activity.

==Database tables==
The data for the course module is stored in the database table 'mdl_course_modules' (the 'mdl_' part will be different if you have chosen a non-default prefix for your database tables). This fields in this table link it to a number of other tables in the database. The 'course' field links to the 'mdl_course' table, which contains everything you need to know about a course. The 'module' table links to the 'mdl_modules' table, which gives information about the type of the module (e.g. 'quiz', 'resource') as well as its current version number. After looking up the type of the module, the rest of the details about this module can be found by looking up the 'instance' value (from the 'mdl_course_modules' table) in the 'mdl_{type}' table. Here you can find the name and introductory paragraph for the activity / resource, as well as information that is specific to the type of activity being looked at.

You can quickly gather all of this information, by using the 'get_fast_modinfo($course)' function. The easiest way to understand the data returned is to use the following code:
<code php>
global $DB;
$course = $DB->get_record('course', array('id' => $courseid));
$info = get_fast_modinfo($course);
print_object($info);
</code>

==Usage==
The cmid (course module id) is used widely throughout Moodle to identify a specific activity / resource. Some of the most important uses are:
* When linking to a modules 'view.php' script, it is passed as the 'id' parameter
* To get the 'context' for the module (used when checking user capabilities or linking files to an activity), via the function call 'context_module::instance($cmid)' (before Moodle 2.2 this was 'get_context_instance(CONTEXT_MODULE, $cmid)')
* Every log entry in 'mdl_log' that relates to a specific activity has the 'cmid' field set

==More documentation==
* [[Module visibility and display]]
* [http://phpdocs.moodle.org/HEAD/core/lib/course_modinfo.html course_modinfo PHPdocs]
* [http://phpdocs.moodle.org/HEAD/core/lib/cm_info.html cminfo PHPdocs]

Talk:Course drag and drop upload

2012-01-19T16:34:38Z

Davosmith:

Note: i'm a little out of touch with the mod/ api, so this may not make mod-type sense.

I think I agree with the basic principle of the design, but rather than '[modname]_dndupload_register' which receives dndupload_handler object, I would go for something of something a bit like the repository API with something like a static '[modname]_supports_dndupload' function which returns which types it supports.

I'm not clear on what can be done with non-file types of drag/drop. Can you give some examples of this? --[[User:Dan Poltawski|Dan Poltawski]] 00:21, 20 January 2012 (WST)

If you want to see what non file types can do, try installing my block. Basically, dragging a URL (from the address bar or from a page) can create a link resource, dragging a selected block of text can create a page resource ... Maybe other people can come up with further examples--[[User:David Smith 2|David Smith 2]] 00:34, 20 January 2012 (WST)

Course drag and drop upload

2012-01-17T18:28:17Z

Davosmith:

This is a proposed design for adding Drag and Drop upload to course pages, in a similar way (from the user's perspective) to the [http://moodle.org/plugins/view.php?plugin=block_dndupload Drag and Drop upload block].

==Goals==

* Allow users, with appropriate editing capabilities, to directly drag files (and links / blocks of text / other data types?) onto a course page and have them appear in the course as appropriate resource / activity types
** There should be as little 'friction' as possible to getting files uploaded - sensible defaults should be automatically applied as much as possible
* Allow different modules to register as handlers of certain file types (based on the file extension) and/or data types (for when a link or some text is dragged & dropped from another application/browser window)
** If there are multiple handlers for any given file/data type (e.g. a 'zip' file could be file resource, be unzipped to create a folder resource or be treated as a SCORM package), then the user should be presented with a list of ways of treating the file and be asked to choose one.
** Default handlers should be included in appropriate core modules (e.g. 'file resource' should handle all file types, 'page resource' should handle dropped text/html, 'link resource' should handle dropped URLs)

==Design==

A class called dndupload_handler will handle the registration of all the different modules with the file/data types that they handle. When an instance of this class is created, it will search for the 'lib.php' file in each subdirectory of '/mod' and then look for a function '[modname]_dndupload_register'. If found, this function will be called and the dndupload_handler object will be passed in as a parameter. This will allow the modules to register the following information:
* For files:
** the extension ('*' to handle all extensions)
** the name of the module to handle this type
** the message to display to users if there is a choice of modules to handle a particular file
* For data types, there are two stages:
** Register the type:
*** an identifier to know it by
*** an array of mime types that it maps to (e.g. 'url' data type can be declared as 'url', 'text/uri-list' depending on browser implementations)
*** the helper text to display when dragging the type over the course (e.g. 'add a link here')
*** the text to display when asking the user for a name for the dropped object (e.g. 'what do you want to call this link?') - needed as, unlike files, dragged urls/text blocks do not have an inherent name
*** a priority (so that 'url' can take priority over 'text/html' and 'text/plain', as often dropped items provide fallback data types)
*** Note some default types - url, text/html, text - will be registered by default within the library code
** Register a type handler:
*** the identifier of the type
*** the module to handle this type
*** the message to display to the user if there is a choice of modules to handle this type

The details about the different types that can be handled will need to be passed onto the initialisation code for the drag and drop javascript code on the page.

The drag and drop code on the page will do the following (most of these are already implemented in the drag and drop upload block):
# Add the necessary dragenter, dragleave, dragover and drop handlers to each course section
# When a drag event is detected for a course section, examine the attached data types and, if it is a recognised type (e.g. 'File', 'text/plain'), display an appropriate message within the course section (e.g. 'Add file(s) here')
# When a drop event is detected, check to see how many handlers are registered for that type (based on the data handed in during initialisation), if none - do nothing, if 1 then fire off an AJAX message to the server with the data and the name of the registered module, if more than 1 handler, then present the user with a YUI dialog with a list of ways to handle the type (using the string registered with the handler, above)
## For non-file types, there will need to be an intermediate step where a YUI dialog is shown to ask the user what to call the resource - where there is also choice of handlers, the two dialogs should be integrated together (e.g. What do you want to call this link? _________ Do you want to create a: [ ] Link to webpage [ ] Link to LTI provider)
# Show a suitable placeholder (the name of the item you are creating) & progress bar / spinner as the file/data is sent to the server
# Replace the placeholder with the name of the item as returned by the server, linked to the newly created module instance, with the standard edit tools initialised beside it

On the server side, the following steps will take place:
# When the AJAX data is received, do the standard checks (e.g. user permissions, sesskey checks, etc)
# Check whether the data is a file or another data type
## For files create a draft files area, note the id of the area and use the 'upload' repository to add the file to this area
## For other data types, just store the data in a variable
# Double-check that the module named in the AJAX data is a registered handler for the type of data in the call
# Create a course module instance for the chosen module (just as if the user had saved the 'add new X module form'), in the course/section detailed in the AJAX data
# Load the lib.php file for the module and call the function [modname]_dndupload_handle, passing in the appropriate data from the browser:
## The draft area id / data (depending on whether it is a file or some other data type)
## The display name (taken from the file name)
## The type (e.g. 'file', 'text/html', 'url')
# The module should then handle all its internal initialisation (equivalent to [modname]_add_instance - but with most values using defaults, instead of getting data from the 'mod_edit.php' form)
# Return the necessary data to the browser - the cleaned module name, the icon, the 'view' URL to link to and the standard editing tools (which can then be overwritten by the AJAX tools on the client side)

[[Category:Project]]