Using the File API in Moodle forms: Difference between revisions

Revision as of 03:50, 31 March 2009

Moodle 2.0

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 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 type. 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.

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.

Process draft area 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 copy 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.)

$messagetext = file_save_files_from_draftarea($messageitemid, $context->id, 'proper_file_area', $post->id, true, $messagetext);

$messageitemid: 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.
$messagetext: this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

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 picker

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

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

@@ Line 29: / Line 29: @@
 ===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,
+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.
-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@@:
+When the user submits the form, we then need to copy 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.)
 <code php>
-$message_text = file_convert_draftarea($message_itemid, $context->id, 'proper_file_area', $post->id, true, $message_text);
+$messagetext = file_save_files_from_draftarea($messageitemid, $context->id, 'proper_file_area', $post->id, true, $messagetext);
 </code>
-$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.
+; $messageitemid : is the variable we retrieved above.
+; $context->id, 'proper_file_area' and $post->id : correspond to the contextid, filearea and itemid columns in the [[File_API#Table:_files|files table]].
+; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.
 ===Move files into draft area===

Documentation