View source for Implementing Course drag and drop upload support in a module

When a user drags and drops files, links or text onto a course, any activity module can register to receive this data. Note that only 'file' support is enabled by default - text & URL handling needs to be enabled under the system 'experimental' features.

To support drag and drop upload, the module needs to add the following two functions to its lib.php file:

== xx_dndupload_register() ==

This should return an array declaring what types of upload it can handle (and, optionally, any extra types that are not supported as standard).

If the module wants to accept files, then it should return something like this: 

<pre><nowiki>
return array('files' => array(
                 array('extension' => 'doc', 'message' => get_string('dosomethingwithdoc', 'mod_xx')),
                 array('extension' => 'pdf', 'message' => get_string('dosomethingwithpdf', 'mod_xx'))
            ));
</nowiki></pre>
This code declares that the particular module wants to handle files ending '.doc' or '.pdf' and also gives the text to display to the user if there is a choice of more than one module to handle that particular file type. Note setting the extension to '*' will mean this module could handle any file type.


To handle non-file types, the return should look something like this:

<pre><nowiki>
return array('types' => array(
                 array('identifier' => 'url', 'message' => get_string('dosomethingwithurl', 'mod_xx')),
                 array('identifier' => 'text/html', 'message' => get_string('dosomethingwithhtml', 'mod_xx')),
                 array('identifier' => 'text', 'message' => get_string('dosomethingwithtext', 'mod_xx'))
             ));
</nowiki></pre>
This declares that the particular module wants to handle all 3 built-in drop types (url, text/html, text) and gives the message to display in each case, if the user has a choice of more than one module to handle that particular type. Note that you can declare support for both 'files' and 'types' by including both in the returned array.


If you need to support the dropping of other types onto the course (in addition to files, text, text/html or url), you can declare the type as below:

<pre><nowiki>
return array('addtypes' => array(
                 array('identifier' => 'newtypename', 'datatransfertypes' => array('newtype', 'text/newtype'), 
                       'addmessage' => get_string('addmessage', 'mod_xx'), 'namemessage' => get_string('namemessage', 'mod_xx'),
                       'priority' => 100)
             ));
</nowiki></pre>
This declares support for a new type, to be known as 'newtypename' (which is the 'identifier' you would need to put in the 'types' array in the previous section). This should be used whenever the browser declares the clipboard data includes one of the types listed in 'datatransfertypes'. Whilst the drag is in progress, the 'addmessage' will be displayed in the current course section (e.g. 'Add a new page here'). Once the drag is complete, the 'namemessage' will be displayed to the user, to get the activity name (e.g. 'What do you want to call this page?'). The priority controls the order in which types are chosen (smaller meaning earlier) - this allows, for example, the 'url' type to be chosen first even when the data could also be interpreted as 'text' type.

== xx_dndupload_handle($uploadinfo) ==

This function receives information about the current upload. It is expected to create a new instance of the module (similarly to how xx_add_instance works) and return the new instance id. If there is a problem, it should return 0 (the coursemodule will then be deleted and the user informed that there was a problem creating the activity).

The data supplied includes:
* $uploadinfo->course - the course object that the upload was dropped onto
* $uploadinfo->displayname - the name the user gave (or the name of the file, after removing the extension and replacing underscores with spaces)
* $uploadinfo->coursemodule - the ID of the coursemodule created to hold this activity
* $uploadinfo->type - the type of upload (either 'Files', or one of the 'types' identifiers listed above)
* $uploadinfo->draftitemid - the ID of the draft area that stores the file the user has uploaded (only for 'Files' type - note there will only be a single file in the area, as multi-file uploads are handled as separate AJAX calls)
* $uploadinfo->content - the raw content dropped onto the browser (only for non-file uploads)

== See also ==
Please take a look at the code for the built-in modules: resource, folder, scorm, url or page for examples of how to use these functions

[[Category:Modules]]
[[Category:Tutorial]]
[[Category:Plugins]]