Document Management API
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
// 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 $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
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.)
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.
Moves the document from its present directory to the specified new one.
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.)
Make $this refer to $old_dms_document. (Think of a UNIX hard link, where the inode -- in our case, id -- gets another reference.)
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
Forcibly unlocks $this.
Make the specified new directory, including necessary parent directories as required (perhaps if an additional boolean parameter is set).
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.
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 the named property in $this->dms_document_properties.
Return a URL that points to the document specified by $this, if possible.
Returns: URL or false
- 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.)
- Using Moodle RFC - Remote object repositories -- consolidating implementations forum discussion