Repository API

This page describes the specification for a future feature, currently being worked on for Moodle 2.0. This spec is STILL UNDER CONSTRUCTION.

See MDL-13766 to track the status of the implementation.

The page is open for everyone so everyone can help correct mistakes and help with the evolution of this document. However, if you have questions to ask, problems to report or major changes to suggest, please add them to the page comments, or start a discussion in the Repositories forum. We'll endeavour to merge all such suggestions into the main spec before we start development.

Note that parts of this document have been now split off into a separate File_API

Objectives

Allow all Moodle users to easily bring content into Moodle from external repositories
Provide a consistent interface to any external repository, for any Moodle module

Use cases

Teacher adding an external file as a new resource

Teacher wants to add a new resource to a course
Teacher clicks the "Choose a resource" button
Teacher is presented with a simple file picker to choose a file (with a menu to switch between multiple configured repositories)
Teacher chooses a file in an external repository
File is COPIED into Moodle and stored by the resource module
File is marked as owned by that user
Whenever someone wants to view that file, the resource module controls access (see File API )

Student submitting an assignment

Student needs to submit an assignment and presses the "Choose files" button
Student sees a "file picker" where they can see files listed on any of several configured repositories (file picker login, file picker browser, file picker search)
Student chooses MySpace from the list
Student is prompted to enter MySpace username/password (if admin allows it, a checkbox could be there to "remember this for next time" but remember security)
Student sees their files in MySpace and chooses one or more
Files are copied from MySpace to Moodle
Assignment module controls the permissions so that only the Student and assignment graders can see the file (other students would not have permission).

Student attaching an image to a forum

Student needs to attach an image and presses the "Choose files" button in the posting screen
Student sees a "file picker" where they can see files listed on any of several configured repositories
Student chooses Mahara from the list
Student is prompted to enter Mahara username/password
Student sees their files in Mahara and chooses one image
Image is copied to Moodle
Image file is attached to forum post by Forum module (by reference)
Forum module controls permissions so that anyone who can read that forum can see that file

Student attaching the same image in another forum

Student needs to submit an assignment and presses the "Choose files" button
Student sees a "file picker" where they can see files listed on any of several configured repositories
Student chooses "Local files" from the list and sees all the files they've uploaded before
A COPY of the image file is attached to forum post by Forum module
Forum module controls access to this file.

Please add more use cases in this same format

Mock screenshots

When you first call up the file picker and choose a repository, you might be asked to log in (if saving of passwords is not allowed):

Browsing files could look something like this:

And you can also search:

General architecture

Each repository plugin (a standard Moodle plugin stored under /repository/xxx) will subclass the standard API and override methods specific to that repository.

As is usual in Moodle, there will be admin settings to disable/enable certain repository plugins as standard, as well as user settings so that users can add their own personal repositories to the standard list (eg Yahoo Briefcase or Google Docs) and to select their default repository.

Once a repository has been used the file will usually be copied into Moodle there and then. However there will also be options to:

only return the URL to the file if it's desired to keep it external (but this does present security and integrity risks), or
refresh the local file copy regularly and automatically
refresh the file manually if desired

Once in Moodle, it is subject to the File API for access control like any other file.

Repository requirements

From the Moodle point of view, each repository is just a hierarchy of nodes.

The repository MUST provide:

A URL to download each node (eg file).
A list of the nodes (eg files and directories) under a given node (eg directory). This allows Moodle to construct a standard browse interface (much like a standard OS file picker). However some repository plugins may choose to completely override the repository_browse() method and implement their own interface, that's OK, as long as they end up with a URL for the file.

The repository can OPTIONALLY:

Require some authentication credentials
Provide more metadata about each node (mime type, size, dates, related files, dublin core stuff, etc)
Describe a search facility (so that Moodle can construct a search form)
Provide copyright and usage rules (or just information about the rules)

Repository plugins

Some plugins I'd like to see developed for the first version are:

local - very similar to the current course-based file manager, except user-based
moodle - an interface to another Moodle site, accessed over a secure mnet connection
jsr170 - an interface that can talk to anything that supports jsr170 (eg Alfresco)
oki - an OKI emulator allowing us to access things with OKI interfaces,like Fedora
briefcase - an interface to Yahoo Briefcase
myspace - an interface to MySpace files (perhaps via this MySpace API)
googledocs - an interface to Google Docs
skydrive - an interface to Microsoft's SkyDrive files
facebook - an interface to Facebook files
merlot - an interface to the learning materials in Merlot.org
flickr - an interface to flickr
youtube - an interface to YouTube
mahara - an interface to a Mahara installation
Dspace - a repository from MIT
DOOR - another popular open source repository
An interface for windows shares e.g. personal folders on network drives. Would need to link with LDAP as usernames will often be wholly/partially the same as network folder names. This could be done using SAMBA, but would also need to work on windows machines natively. See this block for a linux implementation.

Tables

repository

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

Field	Type	Default	Info
id	int(10)		autoincrementing
repositoryname	varchar		A custom name for this repository (non-unique)
repositorytype	varchar		The name of the plugin being used (1 special case: "local" which covers all files uploaded from desktop)
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		username to log in with, if required
password	varchar		password to log in with, if required
option1	varchar		Other information useful to the plugin
option2	varchar		Other information useful to the plugin
option3	varchar		Other information useful to the plugin
option4	varchar		Other information useful to the plugin
option5	varchar		Other information useful to the plugin
timecreated	int(10)		The time this repository was created
timemodified	int(10)		The last time the repository was modified

Invoking the API

Moodle moduleland code doesn't generally need to call the repository API directly. Instead it will add a moodleform item which will invoke the file picker, which in turn will call various repository plugins to create the display.

Repository plugin

Each repository plugin is required to contain the following elements:

Repository class

This class implements the interface to a particular repository, for browsing, selecting and updating files. Repositories can redefine any of these as required (and in some instances, must redefine them):

get_file($path)

Given a URL, get a file from there.

get_listing($parent='/', $search=''')

Given a path, and perhaps a search, get a listing of files.

print_login()

Show the login screen, if required

print_listing

Given a listing from get_listing, print it.

print_search

Print the search form.

store_login($username, $password, $userid=''')

If you do want to cache login details for various repositories, then use this method.

cron()

Defines operations that happen occasionally on cron.

icon.png

A logo that represents the repository

Documentation