Using the File API in Moodle forms

In Moodle 2.o onward, we introduced Repository API to fetch files from external sources, Repository API will move to files into draft areas, then modules will process moving draft area files into a proper fileareas, this documentation will demonstrate how to do that.

There are three form elements involved with Repository API, they are file manager, file picker and editor, the legacy upload button will be replaced by file picker or file manager, file picker and file manager work similar, the only difference is file manager can fetch multiple files, file picker only fetch one file. Editor element is introduced to replace legacy htmleditor element, I will talk about them respectively.

editor element

The editor element has been integrated with file picker, the htmleditor element should be replaced with it: $mform->addElement('editor', 'message', get_string('message', 'forum'), array('maxfiles'=>-1, 'filearea'=>'forum_post')); The editor element can take following options: maxfiles, maxbytes, filearea, subdirs and changeformat. NOTE, the element has included format option of the editor, do not ues format element in moodle form anymore.

To retrieve editor content, you need to use following code: if ($fromform = $mform->get_data()) {

   // content of editor
   $message_text = $fromform->message['text'];
   // format of content
   $message_format  = $fromform->message['format'];
   // draft itemid
   $message_itemid  = $fromform->message['itemid'];

}

Process draft area files

The editor element has been integrated with file picker, after selected pictures or videos by file picker, the url of the files will be inserted into $message_text, nobody is able to see these pictures or videos except current user, because these files are in draft area, we need to call file_convert_draftarea to convert draft area files to a proper file area, it will return text with relative links starting with @@PLUGINFILE@@: $message_text = file_convert_draftarea($message_itemid, $context->id, 'proper_file_area', $post->id, true, $message_text); $post->id will be the final itemid of a file, for example, the files in a forum post will have share a same itemid which is the post id.

Move files into draft area

When editing content, we need to move files to draft area again to edit them, to do so, we need to call // $draftitemid can be null, file_prepare_draftarea will create a new one automatically. // $filearea the file area of files // $itemid the itemid of files file_prepare_draftarea($draftitemid, $context->id, $filearea, $itemid); This function will return relinked embedded url, after editing content, you need to call file_convert_draftarea again to convert draft area files.

Convert relative links starting with @@PLUGINFILE@@ into correct format

Call file_convert_relative_pluginfiles to convert links: $message_text = file_convert_relative_pluginfiles($message_text, 'pluginfile.php', "$context->id/proper_file_area/$itemid/");

file manager

Create file manager element in moodle form

$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'),

  array('subdirs'=>0,
    'maxbytes'=>$maxbytes,
    'maxfiles'=>50,
    'filetypes'=>'*'

)); You can specify what file types are accepted by filemanger, all file types are listed at moodle/lib/file/file_types.mm, this is a freemind file, you can edit it freely, the changes will be reflected in moodle.

Retrieve files

1. Call get_draftarea_info to get how many files in this draftarea
2. Call file_convert_draftarea to convert draft area files to a proper file area