Document Management API

From MoodleDocs
Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.

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?


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


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

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


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

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


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


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

Returns: true/false


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


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


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

Returns: true/false


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


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


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

Returns: $new_dms_document->id, or false


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

Returns: $this->id, or false


Locks $this.

Returns: true/false


Unlocks $this.

Returns: true/false


Forcibly unlocks $this.

Returns: true/false


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

Returns: true/false


Get the present working directory.

Returns: present working directory as a string, or false


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

Returns: true/false


List the files/directories in $pwd.

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


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


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

Returns: URL or false

Other methods


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