Repository plugins embedding external file chooser

Jump to: navigation, search
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.


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:

<object type="[type]" src="[url]" />

An example of generating this can be found in the Equella plugin:

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;

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:

// Extract and decode the return value
$json = required_param('tlelinks', PARAM_RAW);
$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
   <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'; = "$author";
        resource.license = "$license";
// Output the generated javascript
header('Content-Type: text/html; charset=utf-8');

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