Using the File API in Moodle forms

Moodle 2.0

In Moodle 2.0 onwards, 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 file areas, 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.

Form element: editor

When using editor element you need to preprocess and postprocess the data:

1. detect if for already submitted and draft area already exists) - file_get_submitted_draft_itemid()
2. prepare draft file area, temporary storage of all files attached to the text - file_prepare_draft_area()
3. convert encoded relative links to absolute links - file_prepare_draft_area()
4. after submission the changed files must be merged back into original area - file_save_draft_area_files()
5. absolute links have to be replaced by relative links - file_save_draft_area_files()

The file picker has been integrated with with TinyMCE to make the editor element. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example: $mform->addElement('editor', 'message', get_string('message', 'forum'),

       array('maxfiles' => EDITOR_UNLIMITED_FILES, 'filearea' => 'forum_post'));

The editor element can take following options: maxfiles, maxbytes, filearea, subdirs and changeformat. Please note that the embedded files is optional feature and should not be used everywhere.

Note: the element has included format option of the editor. You should no longer use the separate format element type.

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

   // content of editor
   $messagetext = $fromform->message['text'];
   // format of content
   $messageformat  = $fromform->message['format'];
   // draft itemid
   $messageitemid = $fromform->message['itemid'];

} If there are multiple files, they will share the same itemid.

Save the draft files

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function does this. $messagetext = file_save_draft_area_files($post->message['itemid'],

       $context->id, 'proper_file_area', $post->id, true, $post->message['text']);

$post->message['itemid']

is the variable we retrieved above.

$context->id, 'proper_file_area' and $post->id

correspond to the contextid, filearea and itemid columns in the files table.

$post->message['text']

this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

Move files into draft area

In the section about the editor form element, we skipped over a stage, becuase we must prepare the draft area before we show the form, and copy any existing files into it.

The function to do that is prepare_draft_area, which is the opposite of save_files_from_draft_area: $draftitemid = file_get_submitted_draft_itemid('elementname'); file_prepare_draft_area($draftitemid, $context->id, $filearea, $itemid);

$draftitemid

may be 0, in which case a new one will be created automatically. Normally you get this with file_get_submitted_draft_itemid.

$context->id, $filearea and $itemid

correspond to the contextid, filearea and itemid columns in the files table.

$messagetext

as with save_files_from_draft_area, this function will rewrite the links in some content if you pass some content in. In this case, the links are rewritten from the '@@PLUGINFILE@@/' form to point to the actual files in the draft area.

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

Before content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files. $messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',

       "$context->id/proper_file_area/$itemid/");

$messagetext

is the content containing the @@PLUGINFILE@@ URLs from the database.

'pluginfile.php'

there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.

"$context->id/proper_file_area/$itemid/"

uniquely identifies the file area, as before.

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 file_get_draft_area_info to get how many files in this draft area
2. Call file_save_draft_area_files to copy the files to their permanent home in a real file area.

See also

• File API
• Using the file API
• Repository API
• Portfolio API
• MDL-14589 - File API Meta issue