MoodleDocs - User contributions [en]

Using the File API in Moodle forms

2011-07-05T02:15:45Z

Sunner: /* Add file manager element */ The default value of subdirs is 1 not 0. I tried and proved this.

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[File API|File API]], and every file is associated with a component and a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the [[Repository API|Repository API]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[Using_the_File_API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>

==== Obtain the chosen file ====

The API for getting file contents is exactly the same as for ''file'' element.

<code php>
$content = $mform->get_file_content('userfile');
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50, 'accepted_types' => array('document') ));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 1) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;accepted_types:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/filestorage/file_types.mm moodle/lib/filestorage/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle. Example usage: '''array('audio', 'video', 'documents')''', you can include file extensions as well, for example: '''array('*.txt', '*.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');
file_prepare_draft_area($draftitemid, $context->id, 'mod_glossary', 'attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'mod_glossary', 'attachment', $entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two way for using of editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array <code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles, 'maxbytes'=>$maxbytes);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet <code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'), null, $textfieldoptions);</code>
# prepare data <code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>
# get submitted data and after inserting/updating of data <code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. 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:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES));
</code>
The editor element can take following options: maxfiles, maxbytes, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'mod_glossary', 'entry', $entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

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

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

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 and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'mod_glossary', 'entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'component', 'proper_file_area' and $entry->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.

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.

== File serving==

=== Convert internal relative links to absolute links ===

Before text 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.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
$context->id, 'mod_mymodule', 'proper_file_area', $itemid);
</code>
; $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, 'mod_mymodule', 'proper_file_area', $itemid : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes; // Could also use $CFG->maxbytes if you are not coding within a course context
$definitionoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true, 'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context, 'mod_glossary', 'entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'mod_glossary', 'attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'), array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'), 'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null, $definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'), null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2', get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly

=== Handling submitted data ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context, 'mod_glossary', 'entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, 'mod_glossary', 'attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

=== Gotchas ===
A few things to keep in mind:
* Make sure that you instantiate the moodle form before any call to $OUTPUT->header()

== See also ==

* [[File API]]
* [[Using the file API]]
* [[Repository API]]
* [[Portfolio API]]
* MDL-14589 - File API Meta issue

[[Category:Files]]
[[Category:Repositories]]

File API

2011-04-05T04:35:03Z

Sunner: /* File areas */ Fix a typo

{{Moodle 2.0}}
The File API is for managing all the files stored by Moodle. If you are interested in how the file API works internally, see [[File API]]. The page is just about what you need to know to use the file API. Related is the [[Repository API]], which lets users get files into Moodle.

If you are looking for an explanation on how to upgrade pre-2.0 code to using the file API, you most likely need to read [[Using_the_File_API_in_Moodle_forms|Using the File API in Moodle forms]].

==File areas==

Files are conceptually stored in '''file areas'''. A file area is uniquely identified by:
* A context id.
* full component name, for example 'course', 'mod_forum', 'mod_glossary'.
* A file area type, for example 'intro' or 'post'.
* A unique itemid. Normally, the itemid relates to something depending on the file area type. For example, for a 'course', 'intro' file area, the itemid is 0. For forum post, it is the post id.

File areas are not listed separately anywhere, they are stored implicitly in the files table. Please note that each subsystem is allowed to access only own file areas, for example only code in /mod/assignment/* may access files with component 'mod_assignment'.

===Naming file areas===

The names of the file areas are not strictly defined, but it is strongly recommended to use singulars and common names of areas if possible (intro, post, attachment, description, ...).

==Serving files to users==

You must refer to the file with a URL that includes a file-serving script, often pluginfile.php. For example

The general form of the URL is something like
<code php>
$url = $CFG->wwwroot/pluginfile.php/$contextid/$component/$filearea/arbitrary/extra/infomation.ext
</code>

A specific example might be
<code php>
$url = $CFG->wwwroot/pluginfile.php/$forumcontextid/mod_forum/post/$postid/image.jpg
</code>

The file serving script then looks at the context id, and component name, and the file area name, and based on that arranges for the file to be served, following appropriate security checks.

In most cases this is done by calling a callback function in the appropriate plugin, these functions are stored in lib.php files and named component_name_pluginfile() . The arbitrary/extra/infomation.ext is passed to the callback. For example, files in the mod_forum+post file area end up being served by the mod_forum_pluginfile function in mod/forum/lib.php.

You normally use an API function to generate these URL automatically, most often the file_rewrite_pluginfile_urls function.

==Getting files from the user==

* See [[Using_the_File_API_in_Moodle_forms|Using the File API in Moodle forms]]
==Examples==
Please note that in reality developers outside of core will not deal with file api directly in majority of cases, instead use formslib elements which are doing all this automatically.

===Browsing files===
<code php>
$browser = get_file_browser();
$context = get_system_context();

$filearea = null;
$itemid = null;
$filename = null;
if ($fileinfo = $browser->get_file_info($context, $component, $filearea, $itemid, '/', $filename)) {
// build a Breadcrumb trail
$level = $fileinfo->get_parent();
while ($level) {
$params = base64_encode(serialize($level->get_params()));
$path[] = array('name'=>$level->get_visible_name(), 'path'=>$params);
$level = $level->get_parent();
}
$path = array_reverse($path);
$children = $fileinfo->get_children();
foreach ($children as $child) {
if ($child->is_directory()) {
echo $child->get_visible_name();
// display contextid, itemid, component, filepath and filename
var_dump($child->get_params());
}
}
}

</code>

===Moving files around===

For example, if you have just built a file at the path
<code php>
$from_zip_file = $CFG->dataroot . '/temp/backup/' . $preferences->backup_unique_code .
'/' . $preferences->backup_name;
</code>
And you want to move it into the course_backup file area, do
<code php>
$context = get_context_instance(CONTEXT_COURSE, $preferences->backup_course);
$fs = get_file_storage();
$file_record = array('contextid'=>$context->id, 'component'=>'course', 'filearea'=>'backup',
'itemid'=>0, 'filepath'=>'/', 'filename'=>$preferences->backup_name,
'timecreated'=>time(), 'timemodified'=>time());
$fs->create_file_from_pathname($file_record, $from_zip_file);
</code>

===Create a copy of stored file===
TODO: this example is bogus, nobody should ever write code like this (skodak)
If you need to create a copy of stored file (actually, it add a new record in database):
<code php>
$context = get_context_instance_by_id($contextid);
$file_info = $browser->get_file_info($context, $component, $filearea, $fileitemid, $filepath, $filename);
// copy this file to draft area
$file_info->copy_to_storage($user_context->id, 'user', 'draft', $newitemid, '/', $title);
</code>

The above code is intended for user-interface behaviour which respects the current user's permissions. If you need to write code which copies files at the back-end in areas which are not directly editable by users (for example, when copying a glossary entry to another glossary, and you want to copy its attachments), you do not need to use the user-level $browser at all. All operations are carried out with the file_storage object (usually $fs). The method to use is create_file_from_storedfile.

For example, the glossary stores per-entry files in two areas ('mod_glossary', 'attachment' which stores attachments and 'mod_glossary', 'entry' which stores files directly related to the HTML definition, such as embedded images). The following code copies all the files relating to a specific glossary entry from one such area to a different glossary item in a different glossary. Note that it changes the context ID and item ID of each file to represent the new context (for the different glossary module) and the new glossary entry (a new row was added to glossary_entries).

<code php>
$fs = get_file_storage();
if ($files = $fs->get_area_files($oldcontextid, 'mod_glossary', 'attachment', $oldentryid)) {
foreach ($files as $file) {
$fs->create_file_from_storedfile(array(
'contextid' => $newcontextid,
'itemid' => $newentryid), $file);
}
}
</code>

=== List area files ===
<code php>
$fs = get_file_storage();
$files = $fs->get_area_files($contextid, 'mod_assignment', 'submission', $submission->id);
foreach ($files as $f) {
// $f is an instance of stored_file
echo $f->get_filename();
}
</code>

=== Create file ===

Here's how to create a file whose contents will be a text string. This is the equivalent of the PHP function <tt>file_put_contents</tt>.

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
'contextid' => $context->id, // ID of context
'component' => 'mod_mymodule', // usually = table name
'filearea' => 'myarea', // usually = table name
'itemid' => 0, // usually = ID of row in table
'filepath' => '/', // any path beginning and ending in /
'filename' => 'myfile.txt'); // any filename

// Create file containing text 'hello world'
$fs->create_file_from_string($fileinfo, 'hello world');
</code>

If you want to create a file in the Moodle file area based on a 'real' file e.g. in a temporary folder, you can use <tt>create_file_from_pathname</tt> instead.

Unlike with ordinary files, this method will not automatically overwrite an existing file. If you wish to overwrite a file, you must first get the file and (if it exists) delete it, and only then create it again.

=== Read file ===

This is a way to read a file, equivalent to <tt>file_get_contents</tt>. '''Please note your are allowed to do this ONLY from mod/mymodule/* code, it is not acceptable to do this anywhere else.''' Other code has to use file_browser interface instead.

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
'component' => 'mod_mymodule', // usually = table name
'filearea' => 'myarea', // usually = table name
'itemid' => 0, // usually = ID of row in table
'contextid' => $context->id, // ID of context
'filepath' => '/', // any path beginning and ending in /
'filename' => 'myfile.txt'); // any filename

// Get file
$file = $fs->get_file($fileinfo->contextid, $fileinfo->component, $fileinfo->filearea,
$fileinfo->itemid, $fileinfo->filepath, $fileinfo->filename);

// Read contents
if ($file) {
$contents = $file->get_content();
} else {
// file doesn't exist - do something
}
</code>

If you want to access the file directly on disk, this is not permitted. Instead, you need to make a copy of the file in a temporary area and use that. You can do this with <tt>$file->copy_content_to($pathname)</tt>.

=== Delete file ===

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
'filearea' => 'mod_mymodule',
'filearea' => 'myarea', // usually = table name
'itemid' => 0, // usually = ID of row in table
'contextid' => $context->id, // ID of context
'filepath' => '/', // any path beginning and ending in /
'filename' => 'myfile.txt'); // any filename

// Get file
$file = $fs->get_file($fileinfo->contextid, $fileinfo->component, $fileinfo->filearea,
$fileinfo->itemid, $fileinfo->filepath, $fileinfo->filename);

// Delete it if it exists
if ($file) {
$file->delete();
}
</code>

==See also==

* [[File API]] how the File API works internally.
* [[Roadmap|Moodle 2.0 roadmap]]

[[Category:Files]]

File API

2011-04-05T04:33:59Z

Sunner: /* File areas */ Remove a duplicated 'is'

{{Moodle 2.0}}
The File API is for managing all the files stored by Moodle. If you are interested in how the file API works internally, see [[File API]]. The page is just about what you need to know to use the file API. Related is the [[Repository API]], which lets users get files into Moodle.

If you are looking for an explanation on how to upgrade pre-2.0 code to using the file API, you most likely need to read [[Using_the_File_API_in_Moodle_forms|Using the File API in Moodle forms]].

==File areas==

Files are conceptually stored in '''file areas'''. A file area is uniquely identified by:
* A context id.
* full component name, for example 'course', 'mod_forum', 'mod_glossary'.
* A file area type, for example 'intro' or 'post'.
* A unique itemid. Normally, the itemid relates to something depending on the file area type. For example, for a 'course', 'intro' file area, the itemid is 0. For forum post, it is the post id.

File areas are not listed separately anywhere, they are stored implicitly in the files table. Please note that each subsystem is allowed to access only own file areas, for example onnly code in /mod/assignment/* may access files with component 'mod_assignment'.

===Naming file areas===

The names of the file areas are not strictly defined, but it is strongly recommended to use singulars and common names of areas if possible (intro, post, attachment, description, ...).

==Serving files to users==

You must refer to the file with a URL that includes a file-serving script, often pluginfile.php. For example

The general form of the URL is something like
<code php>
$url = $CFG->wwwroot/pluginfile.php/$contextid/$component/$filearea/arbitrary/extra/infomation.ext
</code>

A specific example might be
<code php>
$url = $CFG->wwwroot/pluginfile.php/$forumcontextid/mod_forum/post/$postid/image.jpg
</code>

The file serving script then looks at the context id, and component name, and the file area name, and based on that arranges for the file to be served, following appropriate security checks.

In most cases this is done by calling a callback function in the appropriate plugin, these functions are stored in lib.php files and named component_name_pluginfile() . The arbitrary/extra/infomation.ext is passed to the callback. For example, files in the mod_forum+post file area end up being served by the mod_forum_pluginfile function in mod/forum/lib.php.

You normally use an API function to generate these URL automatically, most often the file_rewrite_pluginfile_urls function.

==Getting files from the user==

* See [[Using_the_File_API_in_Moodle_forms|Using the File API in Moodle forms]]
==Examples==
Please note that in reality developers outside of core will not deal with file api directly in majority of cases, instead use formslib elements which are doing all this automatically.

===Browsing files===
<code php>
$browser = get_file_browser();
$context = get_system_context();

$filearea = null;
$itemid = null;
$filename = null;
if ($fileinfo = $browser->get_file_info($context, $component, $filearea, $itemid, '/', $filename)) {
// build a Breadcrumb trail
$level = $fileinfo->get_parent();
while ($level) {
$params = base64_encode(serialize($level->get_params()));
$path[] = array('name'=>$level->get_visible_name(), 'path'=>$params);
$level = $level->get_parent();
}
$path = array_reverse($path);
$children = $fileinfo->get_children();
foreach ($children as $child) {
if ($child->is_directory()) {
echo $child->get_visible_name();
// display contextid, itemid, component, filepath and filename
var_dump($child->get_params());
}
}
}

</code>

===Moving files around===

For example, if you have just built a file at the path
<code php>
$from_zip_file = $CFG->dataroot . '/temp/backup/' . $preferences->backup_unique_code .
'/' . $preferences->backup_name;
</code>
And you want to move it into the course_backup file area, do
<code php>
$context = get_context_instance(CONTEXT_COURSE, $preferences->backup_course);
$fs = get_file_storage();
$file_record = array('contextid'=>$context->id, 'component'=>'course', 'filearea'=>'backup',
'itemid'=>0, 'filepath'=>'/', 'filename'=>$preferences->backup_name,
'timecreated'=>time(), 'timemodified'=>time());
$fs->create_file_from_pathname($file_record, $from_zip_file);
</code>

===Create a copy of stored file===
TODO: this example is bogus, nobody should ever write code like this (skodak)
If you need to create a copy of stored file (actually, it add a new record in database):
<code php>
$context = get_context_instance_by_id($contextid);
$file_info = $browser->get_file_info($context, $component, $filearea, $fileitemid, $filepath, $filename);
// copy this file to draft area
$file_info->copy_to_storage($user_context->id, 'user', 'draft', $newitemid, '/', $title);
</code>

The above code is intended for user-interface behaviour which respects the current user's permissions. If you need to write code which copies files at the back-end in areas which are not directly editable by users (for example, when copying a glossary entry to another glossary, and you want to copy its attachments), you do not need to use the user-level $browser at all. All operations are carried out with the file_storage object (usually $fs). The method to use is create_file_from_storedfile.

For example, the glossary stores per-entry files in two areas ('mod_glossary', 'attachment' which stores attachments and 'mod_glossary', 'entry' which stores files directly related to the HTML definition, such as embedded images). The following code copies all the files relating to a specific glossary entry from one such area to a different glossary item in a different glossary. Note that it changes the context ID and item ID of each file to represent the new context (for the different glossary module) and the new glossary entry (a new row was added to glossary_entries).

<code php>
$fs = get_file_storage();
if ($files = $fs->get_area_files($oldcontextid, 'mod_glossary', 'attachment', $oldentryid)) {
foreach ($files as $file) {
$fs->create_file_from_storedfile(array(
'contextid' => $newcontextid,
'itemid' => $newentryid), $file);
}
}
</code>

=== List area files ===
<code php>
$fs = get_file_storage();
$files = $fs->get_area_files($contextid, 'mod_assignment', 'submission', $submission->id);
foreach ($files as $f) {
// $f is an instance of stored_file
echo $f->get_filename();
}
</code>

=== Create file ===

Here's how to create a file whose contents will be a text string. This is the equivalent of the PHP function <tt>file_put_contents</tt>.

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
'contextid' => $context->id, // ID of context
'component' => 'mod_mymodule', // usually = table name
'filearea' => 'myarea', // usually = table name
'itemid' => 0, // usually = ID of row in table
'filepath' => '/', // any path beginning and ending in /
'filename' => 'myfile.txt'); // any filename

// Create file containing text 'hello world'
$fs->create_file_from_string($fileinfo, 'hello world');
</code>

If you want to create a file in the Moodle file area based on a 'real' file e.g. in a temporary folder, you can use <tt>create_file_from_pathname</tt> instead.

Unlike with ordinary files, this method will not automatically overwrite an existing file. If you wish to overwrite a file, you must first get the file and (if it exists) delete it, and only then create it again.

=== Read file ===

This is a way to read a file, equivalent to <tt>file_get_contents</tt>. '''Please note your are allowed to do this ONLY from mod/mymodule/* code, it is not acceptable to do this anywhere else.''' Other code has to use file_browser interface instead.

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
'component' => 'mod_mymodule', // usually = table name
'filearea' => 'myarea', // usually = table name
'itemid' => 0, // usually = ID of row in table
'contextid' => $context->id, // ID of context
'filepath' => '/', // any path beginning and ending in /
'filename' => 'myfile.txt'); // any filename

// Get file
$file = $fs->get_file($fileinfo->contextid, $fileinfo->component, $fileinfo->filearea,
$fileinfo->itemid, $fileinfo->filepath, $fileinfo->filename);

// Read contents
if ($file) {
$contents = $file->get_content();
} else {
// file doesn't exist - do something
}
</code>

If you want to access the file directly on disk, this is not permitted. Instead, you need to make a copy of the file in a temporary area and use that. You can do this with <tt>$file->copy_content_to($pathname)</tt>.

=== Delete file ===

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
'filearea' => 'mod_mymodule',
'filearea' => 'myarea', // usually = table name
'itemid' => 0, // usually = ID of row in table
'contextid' => $context->id, // ID of context
'filepath' => '/', // any path beginning and ending in /
'filename' => 'myfile.txt'); // any filename

// Get file
$file = $fs->get_file($fileinfo->contextid, $fileinfo->component, $fileinfo->filearea,
$fileinfo->itemid, $fileinfo->filepath, $fileinfo->filename);

// Delete it if it exists
if ($file) {
$file->delete();
}
</code>

==See also==

* [[File API]] how the File API works internally.
* [[Roadmap|Moodle 2.0 roadmap]]

[[Category:Files]]

DB layer 2.0 migration docs

2010-08-11T08:02:20Z

Sunner: /* The golden changes */ fix a typo (actually two)

{{Template:Development:dmllib 2.0}}{{Moodle_2.0}}
== Introduction ==
Much of the following documentation will not make much sense unless you first read [[XMLDB_Documentation|the XMLDB documentation]]. Please read it first if you would like to join the effort to convert Moodle's code to the new dmllib.

Also, it's recommended to read the whole [[wikipedia:Data_Definition_Language|DDL]] and [[wikipedia:Data_Manipulation_Language|DML]] documentation before start with the migration. That will allow you to have some initial knowledge about the new architecture.

This article defines all the changes that need to be performed in Moodle 1.9 code in order to make it run properly under new Moodle 2.0 DB layer. Changes below are grouped into 2 main blocks ([[XMLDB_Documentation|xmldb]] and [[wikipedia:Data_Manipulation_Language|dml]]) to have them organised. Additional minor changes may be required in the [[wikipedia:Data_Definition_Language|ddl]] code, but won't be documented here.

Although the order of changes showed in this page isn't mandatory at all, it can be interesting to follow it in the migration progress to be able to understand and learn a bit more about all them. That way, you'll end up knowing not only what to change but how and why those changes are required.

Each change will be as simple as possible, representing one easy rule to follow to adapt the code. When anything become too complex to be explained as one simple rule, it will contain one link to the [[dmllib_2.0_examples|examples page]].

For any problem in the migration of code, it's recommended to use the [http://moodle.org/mod/forum/view.php?id=45 Databases forum] at [http://moodle.org moodle.org]. Also if you find any bug in the process, please report it in the [http://tracker.moodle.org/browse/MDL-14679 Moodle Tracker], that way developers will be able to fix it ASAP.

The Glossary module was used as the basis for many of the examples below.

And finally, feel free to complete/fix the list below with the changes you find in the progress of migration, that will certainly help many developers. Thanks!

__TOC__

== check_db_syntax: One helper script ==

Before start migrating your code to Moodle 2.0, it's recommended to install and run the [http://cvs.moodle.org/contrib/tools/check_db_syntax/ check_db_syntax.php] script. Simply copy it to the main folder of your plugin and execute it (from command line or via web). I'll show you the list of old DB usages that need to be transformed following the information below in this article.

If you think that something is missing in the script or have any idea to improve it, feel free to do that yourself, commenting about it in MDL-15237. Thanks!

Also, this (perl-compatible - works in Eclipse, hopefully elsewhere) regex:

(?<!->)(?<!function )(?<!\$)\b(?:(?:count|delete|get|insert|update)_record(?!s_csv)|[gs]et_field|record_exists|execute_sql)|\$CFG->prefix|rs_(?:fetch|close)|(add|strip)slashes(?!_js)

Will find most of the things in your code that need attention, with few false positives.

== XMLDB/DDL changes ==

=== Some comments ===

* When changing DB structures it's highly recommended to use the [[XMLDB editor|XMLDB Editor]] (Admin->Development->XMLDB Editor). It is a safe way to edit install.xml files and to get correct PHP code to be used in upgrade.php scripts.
* If you have some doubts about the list of changes below, it's highly recommended to take a look at some code in core modules, blocks... whatever you need. They are a good reference.
* The most noticeable change (from a migration perspective) in the DDL stuff is that, starting with Moodle 2.0, we have decided to '''drop support for enum (check constraint) fields completely'''. See MDL-18577 and [http://moodle.org/mod/forum/discuss.php?d=118852 this discussion]. That implies changes in different parts of the DB stuff (xml files, function parameters, dropping existing enums...) and are commented with more detail below.

=== The changes ===

* No changes are required in install.xml files at all (that's good news!). Although you must know these:
** The '''ENUM''' and '''ENUMVALUES''' attributes present in your install.xml files will be completely ignored both by the DLL generation stuff and by the XMLDB Editor.
** In Moodle 2.1, those attributes ('''ENUM''' and '''ENUMVALUES''') will be 100% forbidden, so it's highly recommended to erase them since now (Moodle 2.0).
** The XMLDB Editor will detect them when loading any install.xml file and will suggest you to fix that easily with one 1-click® option.
** No matter if you have fixed that with the 1-click® option when loading the files... the [[XMLDB editor|XMLDB Editor]] will save any edited install.xml files without those attributes.
** If your Moodle 1.9.x code '''has some enum defined in the database''', you will need to create one upgrade block (in db/upgrade.php) to drop it (the enum, not the field! ;-) as part of the migration from Moodle 1.9 to 2.0 by using the new '''[[DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' method.
** Of course, if you don't use/like the XMLDB Editor, you can erase them manually with something like this:
perl -p -e 's/ENUM(VALUES)?=".*?" //g' < install.xml > install.xml.new

* All upgrade.php scripts, within the main xxxx_upgrade function must have '''$DB''' (uppercase) in the globals declaration (along with others if needed). Example (from glossary module):
<code php>
function xmldb_glossary_upgrade($oldversion=0) {

global $CFG, $THEME, $DB;
</code>
* All upgrade.php scripts, must NOT have '''$db''' (lowercase) in the globals declaration. Delete it if present.
* After the global declaration in the points above, this line must be present (we'll need it later):
<code php>
$dbman = $DB->get_manager(); /// loads ddl manager and xmldb classes
</code>
* All '''XMLDBTable''' instances in your upgrade code must be replaced by '''xmldb_table''' (no change in parameters)
* All '''XMLDBField''' instances in your upgrade code must be replaced by '''xmldb_field''' (with change in params, both enum and enumvalues are out from function declaration!)
* All '''XMLDBIndex''' instances in your upgrade code must be replaced by '''xmldb_index''' (no change in parameters)
* All '''XMLDBKey''' instances in your upgrade code must be replaced by '''xmldb_key''' (no change in parameters)
* All the '''addFieldInfo()''' methods must be replaced by '''add_field()''' (with change in params, both enum and enumvalues are out from function declaration!)
* All the '''addIndexInfo()''' methods must be replaced by '''add_index()''' (no change in parameters)
* All the '''addKeyInfo()''' methods must be replaced by '''add_key()''' (no change in parameters)
* All the '''setAttributes()''' methods must be replaced by '''set_attributes()''' (with change in params, both enum and enumvalues are out from function declaration!)
* All the DDL functions used in upgrade code, must be transformed as detailed below (it's only about to add '''"$dbman->"''' - without the quotes - before each function call). No changes in parameters are required:
** table_exists ==> $dbman->table_exists
** field_exists ==> $dbman->field_exists
** index_exists ==> $dbman->index_exists
** find_index_name ==> $dbman->find_index_name
** find_check_constraint_name ==> $dbman->find_check_constraint_name ('''DEPRECATED in 2.0. OUT in 2.1''')
** check_constraint_exists ==> $dbman->check_constraint_exists ('''DEPRECATED in 2.0. OUT in 2.1''')
** find_sequence_name ==> '''OUT in 2.0''', see MDL-20349
** create_table ==> $dbman->create_table
** drop_table ==> $dbman->drop_table
** rename_table ==> $dbman->rename_table
** add_field ==> $dbman->add_field
** drop_field ==> $dbman->drop field
** rename_field ==> $dbman->rename_field
** change_field_type ==> $dbman->change_field_type
** change_field_precision => $dbman->change_field_precision
** change_field_unsigned ==> $dbman->change_field_unsigned
** change_field_notnull ==> $dbman->change_field_notnull
** change_field_enum ==> $dbman->change_field_enum ('''OUT in 2.0''', see '''[[DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' to get rid of remaining ENUMs in code).
** change_field_default ==> $dbman->change_field_default
** add_key ==> $dbman->add_key
** drop_key ==> $dbman->drop_key
** add_index ==> $dbman->add_index
** drop_index ==> $dbman->drop_index
* Finally, and not less important, your code (module, block... plugin) must guarantee that it can be upgraded '''ONLY''' from Moodle 1.9, so any previous upgrade code can be safely deleted. '''Moodle 2.0 requires Moodle 1.9''' to be upgraded, so everybody will run the 1.9 => 2.0 upgrade (with other paths like 1.8 => 2.0 not being possible). One good time to clean-up a bit your upgrade code ;-). Don't forget to take a look to the [[XMLDB editor|XMLDB Editor]] and to core modules to see how [http://cvs.moodle.org/moodle/lib/db/upgrade.php?view=markup upgrade.php] files look like in Moodle 2.0.

== DML changes ==

=== Some comments ===
* The ENTIRE CODEBASE requires an update of ALL database query function calls. Expect most moodle files to be affected by this change.

* This is the more complex part to migrate to have the code working under Moodle 2.0, not because of the complexity of the changes themselves (90% of them will be really easy), but because you'll need to triple-check everything works as expected after changes.

* Along the changes below, you'll find links to some examples that will try to make things easier. Anyway, if you are blocked at any point, please ask in forums or tracker (see links at the beginning of the page). Sure it has a good enough solution.

* Once more it's highly recommended to take a look to Moodle core code, searching for similar examples. Of course, new meaningful examples are welcome, and also any clarification in the list of changes below. Feel free to do it, this is a wiki!

* Finally, one more explanation: The changes below have been split into three sections. First one, (called '''"The golden changes"''') are modifications that must be applied to ALL the transformations defined in the second section ('''"The iron changes"'''). Sure you'll understand that after reading them (it's basically a matter of not repeating the golden ones within each iron one, just imagine they are everywhere). Finally other changes details can be found in the '''"The tin changes"''' section.

=== The golden changes ===
''PLEASE read the API before going crazy with search & replace''! You can find all the new methods in lib/dml/moodle_database.php. This is essential because some method signatures have changed (params are different), and some method names have even changed (execute_sql() is now execute()).

Each of the golden changes below is given one short name (G1, G2, G3...) for further reference in the rest of the documentation. Let's go:

* G1: Wherever old functions are used (get_record*, get_field*, set_field, insert_record, update_record, count_records*, delete_records, record_exists), the global $DB must be used as the object on which these functions are called (e.g. get_record_select() becomes $DB->get_record_select()).
<code php>
Example:

// Old syntax
$sql = "WHERE id = 1";
get_record_select($sql);

// New syntax
global $DB;
$sql = "WHERE id = 1";
$DB->get_record_select($sql);
</code>
::Note: for some functions, the $params array is not the second function parameter. For example, set_field:'''
<code php>
// Old syntax
set_field('user', 'firstname', 'Peter', 'id', 1);

// New syntax
global $DB;
$DB->set_field('user', 'firstname', 'Peter', array('id' => 1));
</code>

* G2: All uses of addslashes() '''must be removed'''. They are no longer needed

* G3: All the functions that used to accept a list of string params in the form "param1, value1, param2, value2" now need to be given an array of key=>value pairs as a replacement for these params. Other params remain as before. Check the new API for any exceptions.
<code php>
Example:

// Old syntax:
$user = get_record("user", "firstname", "Peter", "lastname", "Cantrophus");

// New syntax:
global $DB;
$conditions = array("firstname" => "Peter", "lastname" => "Cantrophus");
$user = $DB->get_record("user", $conditions);
</code>
::Note: The example above has been written out in full for clarity. You can use the array() directly within the function call, without using a temporary variable, if you prefer:''
<code php>
global $DB;
$user = $DB->get_record("user", array("firstname" => "Peter", "lastname" => "Cantrophus") );
</code>

* G4: rs_fetch_next_record($rs) is deprecated, in favour of the simple foreach($rs as $var). Calls to rs_close() must be replaced by $rs->close();
<code php>
Example:

// Old syntax
while($result = rs_fetch_next_record($rs)) {
...
}
rs_close();

// New syntax
foreach ($rs as $result) {
...
}
$rs->close();
</code>

* G5: Placeholders must be used for table names. Instead of {$CFG->prefix}tablename, use {tablename}.

<code php>
Example:

// Old syntax
$sql = "SELECT * FROM {$CFG->prefix}user";

// New syntax
$sql = "SELECT * FROM {user}";
</code>

* G6: When PHP variables are used in SQL queries, they must be replaced by parameters. You have the choice between two approaches: ordered parameters, or named parameters.
** Ordered parameters use a simple array of values, which are given to the DML function as $params. The values in the SQL code are simply question marks (?) replacing the values. They are replaced by the DML code one by one, substituting each question mark (?) with the next value in the $params array.
** Named parameters use an associative array of name => value pairs as the $params array. The values in the SQL code are replaced with a colon (:) followed by the key associated with the value, in the $params array. Note that named params '''must be unique''', no matter if the value passed is the same.

<code php>
Examples:

// Old syntax
$sql = "SELECT id, firstname FROM {$CFG->prefix}user WHERE firstname = 'Peter' AND lastname = 'Cantrophus'";
$user = get_record_sql($sql);

// New syntax: ordered params
global $DB;
$params = array('Peter', 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = ? AND lastname = ?";
$user = $DB->get_record_sql($sql, $params);

// New syntax: named params
global $DB;
$params = array('firstname' => 'Peter', 'lastname' => 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = :firstname AND lastname = :lastname";
$user = $DB->get_record_sql($sql, $params);
</code>

To obtain a value for the LIKE operator, include any % signs into the parameter string. For example, code that was previously <tt>"LIKE '$value%'"</tt> becomes <tt>"LIKE ?"</tt> with the parameter <tt>$value.'%'</tt>.

* G7: Replacement of the IN(...) syntax: We no longer hard-code this in our SQL queries, we use a function which determines whether the IN() syntax is needed, or, if there is only one value to compare, the equal (=) sign can be used.

<code php>
Example:

// Old syntax:
$depends_on = array(1, 43, 553);
$gis = implode(',', $depends_on);
$sql = "SELECT *
FROM {$CFG->prefix}grade_items
WHERE id IN ($gis)";
$items = $DB->get_records_sql($sql);

// new syntax
global $DB;
$depends_on = array(1, 43, 553);
list($usql, $params) = $DB->get_in_or_equal($depends_on);
$sql = "SELECT *
FROM {grade_items}
WHERE id $usql";
$items = $DB->get_records_sql($sql, $params);
</code>

'''Note:''' to combine the last two, do the G7 IN SQL stuff first to generate the params array, then do something like
$param['firstname'] = 'peter';
to add the stuff for G6

=== The iron changes ===

*I1: Originally the '''sql_substr()''' function was used without parameters and it returned only the name of the "substring" function to be used under each DB. In Moodle 2.0 and upwards, it has 3 parameters (2 being mandatory) and it returns the complete SQL text to be used when handling substrings. Note that positions in this function are 1-based (first char has index 1).

<code php>
Example:

// Old syntax
$records = get_records_sql("SELECT " . sql_substr() . "(firstname, 1, 20)" . " FROM ... ..."

// New syntax
$records = $DB->get_records_sql("SELECT " . $DB->sql_substr('firstname', 1, 20) . " FROM ... ..."
</code>

=== The tin changes ===
List of minor changes

* T1: Originally get_records() and similar functions were returning false if no records found. All these methods are now always returning arrays, empty array in case of no records found. Please note that get_record() still returns false if specified record not found.
<code php>
Example:

// Old syntax
if (!$posts = get_records('forum_posts', 'parent', 666)) {
$posts = array()
}

// New syntax
global $DB;
$posts = $DB->get_records('forum_posts', array('parent'=>666));
</code>

* T2: Originally DML functions were returning ''false'' if error occurred - ''dml_exception'' is thrown now instead.
<code php>
Example:

// Old syntax
$record = new object();
$record->course = 5;
if (!$id = insert_record('sometable', $record)) {
error('can not insert new record');
}

// New syntax
global $DB;
$record = new object();
$record->course = 5;
$id = $DB->insert_record('sometable', $record);
</code>

== See also ==

* [[XMLDB Documentation|XMLDB Documentation]]: where both xmldb and ddl stuff is explained.
* [[DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.
* [[DDL exceptions|DDL exceptions]] - DDL exceptions information.
* [[DML exceptions|DML exceptions]] - DML exceptions information.

Developer documentation

2006-08-30T05:39:07Z

Sunner: /* See also */

==Guidelines==
The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:
*[[Coding|Coding guidelines]] have to be followed by all Moodle developers
*[[Moodle architecture]] spells out the basic design goals behind Moodle
*[[Interface guidelines]] aim to provide a common feel to the Moodle user interface
*[[CVS (developer)|Moodle CVS for developers]] explains how to work with the Moodle code in CVS
*[[Unit tests]] explains how to run the unit tests, and how to write new test cases.
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc

== Resources and tools ==

*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle
*[http://tracker.moodle.org/ Moodle bug tracker] - bug reports, feature requests and other tracked issues
*[http://moodle.org/mod/forum/view.php?id=55 General developer forum]
*[http://moodle.cvs.sourceforge.net/moodle/moodle/ CVS code] - browse the Moodle code via the web
*[http://moodle.org/xref/nav.html?index.html Cross reference] - phpxref output for browsing Moodle source code
*[http://moodle.sourceforge.net/dhawes-phpdoc/ Moodle PHP doc reference] - automatically generated documentation
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course
*[http://developer.yahoo.com/yui YUI documentation] - YUI is the official AJAX library in moodle.
*[[Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to HEAD

==How you can contribute==

The M in Moodle stands for 'Modular'. There are many different types of components that you can contribute that can be plugged into Moodle to provide additional functionality. When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 database of Moodle modules and plugins]. The following types of plugins currently exist (in alphabetical order):
*[[Modules (developer)|Activity modules]]
*[[Assignment types]]
*[[Authentication|Authentication methods]]
*[[Blocks Howto|Blocks]]
*[[Course formats]]
*[[Database fields (developer)|Database fields]]
*[[Database presets]]
*[[Enrolment plugins (developer)|Enrolment plugins]]
*[[Filters (developer)|Filters]]
*[[Question_engine]]
*[[Question import/export formats]]
*[[Question types|Question types teacher docs]]
*[[Question_engine#Question_types|Question types developper docs]]
*[[Quiz reports]]
*[[Resource types]]
*[[SSO plugins]]

There are also ways you can contribute that don't involve PHP programming:
*[[Themes]]
*[[Translation]]
*[[Database Schemas|Database schemas]]

You can also help a lot by
*[[Tests|Testing]]
*[[Bug tracker|Participating in the bug tracker]]

==Plans for the future==
Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystalize on the forums they can be summarized in this wiki, either as part of the [[Roadmap]] or in the form of [[Developer notes]]. These pages then form the basis for further discussion in the forums.
*[[Roadmap]]
*[[Developer notes]]
*[[Student projects]]
*[[Developer conference|Developer conferences]]

==Documentation for core components==
This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes]] or on the [[Roadmap]].

*[[UTF-8 migration|Migration to UTF-8]]
*[[Question engine]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]
*[[Authentication API]]
*[[Stats package]]
*[[Email processing]]
*[[Cookieless Sessions]]

==Documentation for contributed code==
Many Moodle users contribute code for the benefit of other Moodle users. This can take the form of new activity modules, blocks, themes, resource plug-ins, assignment plug-ins, question type plug-ins, question import/export formats, quiz report plug-ins, course formats, ... This code is initially posted on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course and then often go into the [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/ contrib area] of the Moodle [[CVS]] repository. When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 database of Moodle modules and plugins]. Developer documentation for these components should be listed here.

==See also==
*[http://security.moodle.org/ Moodle Security Centre]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services

[[es:Documentación para Desarrolladores]]
[[fr:Documentation développeur]]
[[zh:开发者文档]]

User talk:Helen Foster

2006-07-22T13:31:57Z

Sunner:

== More hierarchy ==

Hi Helen, I think this wiki is very useful and I would like to thank you for the work you are putting into it. I like your navigation boxes on the module pages. I have a suggestion for extending these: I think it would be nice to have an extra link that allows one to go higher up in the hierarcy to [[Teacher_documentation]]. What do you think? --[[User:Delius|Delius]] 17:48, 26 January 2006 (WST)

:Hi Gustav, thanks for your kind words. Your contributions to the documentation are most welcome. Please feel free to edit [[Template:Quizzes]] or any other template page. You may also wish to consider further use of category pages e.g. [[:Category:Teacher]] for navigation. -- [[User:Helen|Helen]] 18:26, 26 January 2006 (WST)

== Do you monitor every article and talk page? ==

Helen, I have posted another question for you on [[Talk:mod/quiz/index]]. Do you get alerted to anything I put on any talk page or should I post on this page if I want you to see it? --[[User:Delius|Delius]] 18:01, 26 January 2006 (WST)

:Hi Gustav, please note that I often check [[Special:Recentchanges|Recent changes]] or the rss feed. --[[User:Helen|Helen]] 18:26, 26 January 2006 (WST)

::Yes, the [[Special:Recentchanges|Recent changes]] page is very useful. You can tell that I have never used a wiki intensively before. Thanks for your tips. --[[User:Gustav|Gustav]] 18:35, 26 January 2006 (WST)

:::Hey, let's discover the wiki way together! :-) --[[User:Helen|Helen]] 00:24, 27 January 2006 (WST)

Helen, Just a thanks for your wonderful edits which make things look good and are reminders to me to hit that show preview button..again... and again....and then review the whole page. But I have so little to do, so much time :) Bless you.--[[User:chris collman 2|chris collman 2]] 21:13, 28 June 2006 (WST)

:Hi Chris, your kind words are much appreciated :-) Thanks for your contributions to the documentation. --[[User:Helen Foster|Helen Foster]] 06:50, 29 June 2006 (WST)

==Moodle profile==

Helen- I think you should link to your moodle profile like Martin does (assuming you have one, which I assume <grin>). -- D.I. 29Jan06
Wow, you're fast.. .or I'm confused. --D.I. 29Jan06

:Hi D.I. thanks for your suggestion, which [[User:UrsHunkler|someone else]] seem to be following up! ;-) --[[User:Helen|Helen]] 05:00, 30 January 2006 (WST)

== German moodle docs possible? ==

Hello Helen,

thank you very much for these nice and structured doc pages.
When do you plan to launch a german part of the docs.moodle.org pages?
I ask these question because i can translate some of the english doc pages to german.

Greetings Christoph

:Hi Christoph, thanks for your kind offer of translation. Please email ''docs AT moodle DOT org'' so I may get in touch with you easily when the German Moodle documentation is launched. --[[User:Helen|Helen]] 05:17, 30 January 2006 (WST)

== German User Docs ==

Thanks a lot, Helen, for all your work.
I would also like to help with the German version.

Ulrike

:Hi Ulrike, thanks for your kind offer too. MoodleDocs in other languages will happen soon, for sure! --[[User:Helen|Helen]] 08:30, 31 January 2006 (WST)

== Documentation for different versions ==

Helen

Is there a mechanism for specifying which version of Moodle a particular document refers to? If, for instance, a feature is only available in version 1.6, how would a 1.5.3 user know they couldn't follow these instructions?

Equally, if something is done differently in two versions, how would we stop an edit war breaking out between 1.5.3 and 1.6 users?

I appreciate this probably isn't an issue just yet, but it's possible it may become one in later versions.

Cheers,

[[User:CHRISF|CHRISF]] 19:20, 1 February 2006 (WST)

:Hi ChrisF, thanks for highlighting the issue of differences in Moodle versions. Perhaps a Moodle 1.6 template, inserted using the code <code><nowiki>{{Moodle 1.6}}</nowiki></code>, may be used to show features specific to Moodle 1.6. What do you think? --[[User:Helen|Helen]] 04:22, 4 February 2006 (WST)

::Good idea. I think that would clear it up nicely. [[User:CHRISF|CHRISF]] 18:08, 7 February 2006 (WST)

==Hungarian Moodle Docs==

Hello Helen,
I may be knocking at the wrong door.
Could you please create a folder for me to start Moodle documentation in Hungarian please?
Thanks a lot.
Karoly

(Karoly Fabricz, kfabricz AT vnet DOT hu)

:Hi Karoly, thanks for your kind offer. Please read the information on [[MoodleDocs:Starting MoodleDocs|starting Moodle Docs in another language]]. I'll be in touch soon. --[[User:Helen Foster|Helen Foster]] 17:09, 15 March 2006 (WST)

== Belarusian Docs is possible? ==

Dear Helen,

I would like to manage Moodle documentation on Belarusian. Could you create a folder for me to start Moodle documentation in Belarusian, please? Аlphabetic acronym of Belarusian language is be.

Sincerely,
Maryia Davidouskaia
(maryia at iatp dot by)

:Hi Maryia, thanks for your kind offer. As I said to Karoly, please read the information on [[MoodleDocs:Starting MoodleDocs|starting Moodle Docs in another language]], and remember that the more people that are involved in creating the documentation, the better it will be. I'll be in touch soon. --[[User:Helen Foster|Helen Foster]] 17:09, 15 March 2006 (WST)

Ok, You are a STAR!

== Template styles ==
Hi Helen! I noticed that you reverted my edits on [[Template:Book]] and [[Template:Assignments]]. You were right -- I didn't realise that the [[MoodleDocs:Styling|style]] doesn't match [[MoodleDocs:Style guide|moodle.org style]]. However, the current template doesn't look right either. It should float to the right instead of occupying a substantial part of the upper screen (for eg. on [[Calculated question developer docs]] page) -- this wil provide easier navigation. Also, the tempalate should be colorful and/or bordered -- this looks more attractive and the reader can understand that it is not a part of the article. May be we can have orange or similar colored templates (such as [[Template:Large Installations]] and [[Template:excerpted from Jason Cole]]) that match with moodle.org style? Is there any official style documentation? Is there a moodle.org style guide which describes styles for templates -- I couldn't find one? [[User:Utkarshraj Atmaram|Utkarshraj Atmaram]] 17:40, 30 March 2006 (WST)

:Hi Utkarshraj, thanks for your contributions to Moodle Docs. As you've found, [[MoodleDocs:Style guide]] and [[MoodleDocs:Styling]] contain all the Moodle Docs styling documentation to-date. Please add your comments about template styling to [[MoodleDocs talk:Styling]]. --[[User:Helen Foster|Helen Foster]] 17:26, 31 March 2006 (WST)

::Thank you! I've started the discussion at [[MoodleDocs talk:Styling]]. [[User:Utkarshraj Atmaram|Utkarshraj Atmaram]] 19:14, 31 March 2006 (WST)

:::LoL, I just realized that the problem is not with the templates, but with themes. Templates just look find with the MoodleDocs theme, but when I am logged in, I use MonoBook theme -- it doesn't display them as right-aligned (at Wikipedia, we explicity make the templates right-aligned). Sorry for wasting your time! [[User:Utkarshraj Atmaram|Utkarshraj Atmaram]] 14:44, 18 April 2006 (WST)

== Slovak Moodle Documentation ==

Hi, Helen. We would like to start work on translation on Moodle Slovak (sk) documentation. Please, do you think is it possible? Thank you.

Sincerely, Juraj Chlebec
havran@gmail.com

:Hi Juraj, thanks for your offer. Please note that, for non iso-8859-1 languages we need to wait for moodle.org to be converted to UTF-8 (since Moodle Docs authenticates against moodle.org) before setting things up. I'll be in contact when this is done. --[[User:Helen Foster|Helen Foster]] 22:05, 10 April 2006 (WST)

== Polish Moodle Documentation ==

Hello, Helen. I saw Your comments to Juraj's post, so just want to let you know that we are ready to start polish translation. Hope the situation will change soon.

== Removing erroneous pages ==

How can unsuitable pages be removed? I just found [[RHLANGUAGE]] which is not documentation-quality...
Maybe you could do it (please) Helen? Not sure.

Best, Dan
--[[User:Dan Stowell|Dan Stowell]] 04:24, 4 May 2006 (WST)

:Thanks Dan, for future reference please add the deletion template, <code><nowiki>{{Deletion}}</nowiki></code>, to any unsuitable page you find. --[[User:Helen Foster|Helen Foster]] 04:45, 5 May 2006 (WST)

== Request for help (check) ==

Hi, Sun, could you check this page: https://docs.moodle.org/en/Release_Notes
all the info written both in 1.6 and 1.5.4 relative to the Authorize plugin? Ethem Evlice requested me to do so, but you know, I'm not the best English checker in the world! ;-) [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 17:35, 11 May 2006 (WST)

:NP Sol, I've done as requested :-) --[[User:Helen Foster|Helen Foster]] 19:51, 15 May 2006 (WST)

== Moodle Doc Is Great ==

You have done a great job and inspired me to use Media Wiki!

:Thanks Martin, though it's everyone's contributions that make Moodle Docs a great resource! --[[User:Helen Foster|Helen Foster]] 06:36, 24 May 2006 (WST)

== Moodle Docs Wiki accidentally switched to Portuguese? ==

Hi Helen, all of the built in Mediawiki content is appearing in Portuguese for me, both before and after I log in. Perhaps an admin setting that's been accidentally changed? --[[User:David Scotson|David Scotson]] 17:36, 27 Maio 2006 (WST)

:To clarify, only some of the Mediawiki content is in Portuguese. If I go to to the user preferences and choose Portuguese it changes even more text. Changing back to English only returns some text to English. However, choosing French changes all Mediawiki text to French. From this I'm guessing that someone may have overwritten some of the english language files on the server with Portuguese ones. --[[User:David Scotson|David Scotson]] 17:40, 27 Maio 2006 (WST)

::Hi David, yes the [[Special:Allmessages|System messages]] were overwritten by accident. Anyway, it's fixed now and I've learnt from the experience ;-) --[[User:Helen Foster|Helen Foster]] 19:39, 28 May 2006 (WST)

== tr wiki ==

Hi Helen,

Can you arrange for a wiki https://docs.moodle.org/tr (Türkçe) to be set up.

:Thanks Ethem, I'll do so as soon as possible. --[[User:Helen Foster|Helen Foster]] 17:12, 15 June 2006 (WST)

== Finnish Moodle Docs? ==

Hello Helen!

I'm interested in starting and overlooking the Moodle Docs in Finnish. Can you set up https://docs.moodle.org/fi/? My email is samuli DOT karevaara AT lamk DOT fi.

Regards, --[[User:Samuli Karevaara|Samuli Karevaara]] 14:14, 12 June 2006 (WST)

:Helen, thanks, I see that https://docs.moodle.org/fi/ just happened :-). And by the way, you already undid my "This section is unfinished" that I wrote on the front page two minutes before you wrote the "Welcome to Moodle Docs in Finnish" :-) --[[User:Samuli Karevaara|Samuli Karevaara]] 01:04, 14 June 2006 (WST)

::Wow Samuli, you're so fast! Sorry for deleting your text. You're now an admin so you may rollback changes if necessary ;-) --[[User:Helen Foster|Helen Foster]] 01:53, 14 June 2006 (WST)

== Translation to Bosnian languages ==

Hi Hellen,

I'm exploring the Moodle environment for DLE LMS support for one projec that I work in the former Yugoslavia countries. I'll translate documentation for my own sake, and if I can contribute to Moodle have translated documentation in four south-east europen conutries (Bosnia, Croatia, Montenegro, Serbia) it will be my pleasure. Just give me the hint how I can start this.

Best, Latif

:Hi Latif, thanks for your kind offer. Please read the information on [[MoodleDocs:Starting MoodleDocs|starting Moodle Docs in another language]]. Croatian is included in the list of [[MoodleDocs talk:Starting MoodleDocs|languages currently awaiting Moodle Docs]]. I hope it will be set up soon. --[[User:Helen Foster|Helen Foster]] 17:42, 15 June 2006 (WST)

== Word Censorship Page ==

Hi Helen,

Note sure why you deleted some of this page. The idea is (partly) to provide instructions on how to use the settings page of the filter. You also removed the 'see also' back to the main filters administration page. I'm not sure what's wrong with that either. Your advice appreciated :-)

--[[User:Howard Miller|Howard Miller]] 22:54, 20 June 2006 (WST)

:Oh, sorry Howard for not explaining my changes to [[Word censorship]]. I deleted text duplicated on the Word censorship settings page in Moodle and removed the See also link since [[Filters (administrator)]] is listed in [[:Category:Filter]]. However, please feel free to revert any/all of my changes. Your contributions to the documentation are always appreciated :-) --[[User:Helen Foster|Helen Foster]] 17:03, 21 June 2006 (WST)

::That's cool Helen. So is that the rule - don't put stuff in the docs that is already in the built-in help?? --[[User:Howard Miller|Howard Miller]] 18:15, 21 June 2006 (WST)

:::The [http://moodle.org/help.php?file=index.html Moodle help files] will remain in each language pack and so it is not necessary to include their text in this documentation, however sometimes it makes things clearer to do so, at least to start with. --[[User:Helen Foster|Helen Foster]] 15:46, 22 June 2006 (WST)

== translation moodle docs to Korean... ==

You did great jobs! Thanks...
We want to translate Moodle Docs to Korean languages.
Please open ko field...

:Hi, thanks for your offer. Please read the information on [[MoodleDocs:Starting MoodleDocs|starting Moodle Docs in another language]] and find out how many people are interested by discussing Moodle Docs in your moodle.org [http://moodle.org/course/category.php?id=3 community discussion] course. --[[User:Helen Foster|Helen Foster]] 15:42, 22 June 2006 (WST)

== Contrib code documentation ==

Hi Helen,

Where would you suggest I document contrib code. I have some documentation for the Moodle for Mobiles project which installs in {yourmoodleroot}/mobile The code is in cvs in contrib/mobile. It is general documentation about what MFM does.

I guess the place to put it would be https://docs.moodle.org/en/mobile

Jamie

:Hi Jamie, actually the project already has a page, [[Moodle for Mobiles]] ;-) though [[mobile]] could redirect to it. You're also welcome to use any documentation pages linked to Moodle for Mobiles pages in Moodle 1.6. --[[User:Helen Foster|Helen Foster]] 15:56, 22 June 2006 (WST)

::Thanks Helen!! Adding the documentation now. Will redirect from mobile as well. [[User:Jamie Pratt|Jamie Pratt]] 16:08, 22 June 2006 (WST)

:::Cool Helen you did the redirect for me. Thanks for your very speedy response to my enquiry and all your help! -- [[User:Jamie Pratt|Jamie Pratt]] 16:22, 22 June 2006 (WST)

== Chinese Moodle Documentation==
Hi Helen,

I'd like to launch the Chinese Moodle Documentation translation. As I know, MediaWiki has the function that convert charset between Simplified Chinese(GB2312, GB18030) and Traditional Chinese(BIG5). So maybe it's no need to create two.

Now I'm a translator of moodle and maintain a special moodle Chinese version.

--[[User:Sun Sunner|Sun Sunner]] 21:31, 22 July 2006 (WST)