Document Management API

Jump to: navigation, search

Note: You are currently viewing documentation for Moodle 1.9. Up-to-date documentation for the latest stable version is available here: Document Management API.

This page is for (rapidly!) designing the new DMS APIs. As Martin says, "Basically we'll have an API that interfaces Moodle files handling everywhere via a plugin to the chosen repository (or repositories). This allows us to use all the great repositories are around without needing to restrict ourselves to just one." (relevant forum post)

This is an interesting thing to do, because some DMS backends will provide features that others don't provide, and Moodle will/may have to provide those features transparently for backends that don't.

This is a first pass at doing this, and the naming conventions I'm using are intended to be clear but not necessarily to indicate what I think these things should really be called in code.

DMS Properties Object

class dms_document_properties

var $id;

var $name;

var $author;

var $directory;

// every time a separate module/instance refers to this document, refcount is bumped. When refcount==0, bye-bye, document!

// Hopefully most DMS backends will already implement this sort of thing themselves, so those plugins don't have to mess with this.

var $refcount;


var $credentials; // username, password, stuff like that


/* OK, some shameless module promotion here. I've implemented a generic access_control module that I think could be useful here. Maybe it's duplicating some other functionality I just don't know about yet and maybe it has horrible problems that haven't been pointed out to me yet, but I'll mention it here just the same. It's under contrib/ in the portfolio module. */

var $access_control; // object with access control specification/methods

DMS Data Object

class dms_document

var $dms_document_properties;

var $content;

var $pwd; // I'm not sure I like this. You can traipse around the filesystem carrying $content and the content's $dms_document_properties->directory along with you?

Methods

/* This is just a first pass to get something on the table. */

get_document_content();

Content of the document sufficiently specified by $this->dms_document_properties is fetched from DMS backend.

Returns: value of $this->id, or false


put_document_content();

Content of document sufficiently specified by $this->dms_document_properties is stored/updated in DMS backend.

Returns: value of $this->id, or false


get_document_properties();

Full properties of the document sufficiently specified by $this->dms_document_properties (id, owner, title, etc.) are fetched from DMS backend.

Returns: dms_document_properties object, or false


access_change($access_object);

Change the access un/specified for $this according to the $access_object specification (type of access, grant/deny/revoke, designee, etc.)

Returns: true/false


access_test($access_object);

Check to see whether the specified $access_object describes access that has been granted to $this.

Returns: true if specified access is granted, false otherwise


delete();

Decrements the refcount and deletes $this if refcount==0. Hopefully most DMSes already have their own refcount (or whatever); I"m shooting from the hip here.

Returns: true/false


move($new_directory_path);

Moves the document from its present directory to the specified new one.

Returns: true/false


link_that_to_me($new_dms_document);

Make $new_dms_document's directory, name, owner, etc., refer to $this. (Think of a UNIX hard link, where the inode -- in our case, id -- gets another reference.)

Returns: true/false


link_me_to_that($old_dms_document);

Make $this refer to $old_dms_document. (Think of a UNIX hard link, where the inode -- in our case, id -- gets another reference.)

Returns: true/false


copy_this_to($new_dms_document);

Copies $this into the directory_path, owner, title, etc. specified by $new_dms_document.

Returns: $new_dms_document->id, or false


copy_this_from($old_dms_document);

Copies $old_dms_document into the directory_path, owner, title, etc. specified by $this.

Returns: $this->id, or false


lock();

Locks $this.

Returns: true/false


unlock();

Unlocks $this.

Returns: true/false


break_lock();

Forcibly unlocks $this.

Returns: true/false


mkdir($new_dir);

Make the specified new directory, including necessary parent directories as required (perhaps if an additional boolean parameter is set).

Returns: true/false


pwd();

Get the present working directory.

Returns: present working directory as a string, or false


chdir($new_directory_path);

Change PWD to the specified $new_directory_path, which can be absolute or relative.

Returns: true/false


list();

List the files/directories in $pwd.

Returns: array of document_properties of all the files/directories in $pwd, or false


get_property($property_name);

Get the named property from $this->dms_document_properties.

Returns: value of property, or false (er... 'false' on failure?)


set_property($property_name, $value);

Set the named property in $this->dms_document_properties.

Returns: true/false


get_my_url();

Return a URL that points to the document specified by $this, if possible.

Returns: URL or false

Other methods

change_owner();

Other Considerations

  • Will the plugged-in DMS store access controls, or will Moodle handle those? (I think it best to let Moodle handle them but perhaps also pass-through as well as possible; not all external DMSes will have the same or sufficient access controls.)

See also