MoodleDocs - User contributions [en]

Files usability 2.3

2012-11-07T02:34:59Z

Nicolasconnault: /* Background */

{{Infobox Project
|name = Files Usability 2.3
|state = Specifications, feedback sought
|tracker = MDL-31907
|discussion =
|assignee = Moodle HQ DEV team
}}
{{Moodle 2.3}}

[[Image:comicstrip-miscommunication.png|600px|The team was also asked to get rid of bugs in stables.]]

==Background==

The file handling of Moodle 1.x was a very simple system with basically one server directory of files per course and very basic access controls. This system had the benefits of being simple, which meant it was easy to understand and to perform hacks around, but its naivety had a lot of disadvantages in security, consistency, disk use, activity portability, and in some cases even led to dataloss. It also encouraged a certain workflow of "dumping" huge amounts of content into the course in an unstructured way.

The Files system was re-designed in Moodle 2.0 to solve these problems by introducing a model where files are directly associated with texts and "file areas" within different plugins in Moodle, and access to them is finely controlled by those same plugins. For some examples, the assignment module is now able to control access to assignment submissions depending on due dates and so on. Backups now accurately contain all the files they need, and multiple copies of the same file take up no more disk space than a single copy. Files can be drawn as easily from external repositories as from your own computer. The files system in Moodle 2.0 is more capable and detailed than pretty much any other system around.

However, the interfaces to CONTROL all this had to increase significantly in complexity, and this, combined with limited development time and technical constraints in web browsers have led to a large drop in usability. Not only do Moodle users have to contend with a different mindset when adding their resources to Moodle, but they also had to contend with a long list of unfamiliar interface issues.

This project aims to make large improvements in the interface when dealing with files in Moodle and improve usability significantly in Moodle 2.3.

==Critical problems==

This short list of problems has been identified from user feedback via Moodle partners, tracker issues with votes, user surveys, usability studies and common sense. It's not exhaustive, but covers the most severe issues that we think need to be fixed. If you'd like to comment about this list, please use the discussion page for this project or comment directly on the linked tracker issues.

===Problem A: Uploading files take a lot of clicks ===

The most common case for most people is to upload files from their own desktop (not a repository). Since the file picker must be used for this, this can take a lot of clicks, and only one file can be uploaded at a time (unless you know how to use zip).

====Solution A1: Allow drag+drop files from desktop.====

We can add the ability to drag files from the desktop in multiple places. See other issue below about licensing.

# File manager form elements - this is already implemented in 2.3
# Into file picker (private files)
# Into file picker (upload)
# Into course sections (auto-creation of file resources)
# Into HTML editor window? (could add to filearea and insert link/image into text?)

====Solution A2: Add "quick upload" buttons that bring up dialog as quickly as possible====

We can add small buttons that take the user directly to a browse-and-upload button as fast as possible, in the following places:

# File manager form element
# HTML editor image dialog
# HTML editor media dialog

eg see MDL-27236

====Solution A3: Allow multiple files to be uploaded at the same time====

We can add the ability to browse/select multiple files from the desktop via one form, along with a way to update license information for all of them before saving.

This requires some sort of parameter from the calling form to be passed to the file picker, indicating how many new files are expected/allowed.

====Solution A4: More stickiness in file picker between invocations====

The file picker should remember more of your settings from the last time you used it.

# Last Icon/List view
# Last server files location

====Solution A5: Add infrastructure for default licensing, and license editing====

We need some infrastructure for licensing to set default licenses at site/course/user level, because there will be no opportunity to select that at upload time during a drag and drop. File manager form elements should have an "Info" item (in the context menu for each item) that gives a dialog to edit name/license.

====Solution A6: Where possible, link directly to the editing form for file areas====

In areas like "Private files", "Assignment submissions", and "Restore backup" we can probably link users directly to the editing page of the filearea, rather than showing them the browse version first.

===Problem B: Private files management===

The 'Private files" area is the main place that all users have to store files privately in Moodle. It is like a mini-repository that people can use to store files before sharing them in courses and other public places.

====Solution B1: Prevent leaving the Private Files page until changes are saved====

A big problem for people currently is that they can leave the filemanager page before saving their changes. A simple fix is to detect this situation just like Gmail and our Tracker do, and throw up a dialog to confirm they want to do this. The "Save" button can also be more a lot more obvious (should we also offer auto-save?)

====Solution B2: Allow multiple uploads directly via Filepicker repository page====

In the file picker, we should allow people to upload files directly into their Private files and then select it for use in whatever filearea they were editing, all in one step.

====Solution B3: Allow users to "link" to files in their private files====

Add the linking ability to private files, so that people can manage and update multiple copies of files.

===Problem C: File picker looks "ugly"===

Many people say that they just don't like the "MS Windows" look of the current filepicker. This look has been somewhat dictated by the choice of YUI2 to implement it, but it can be improved a lot.

====Solution C1: Improve default graphics styling/layout for the dialog====

It needs to look more like the rest of the Moodle interface.

It should use lightboxing to prevent access to the page, and should be larger by default.

Thumbnails and titles should flow more nicely with less cropping.

====Solution C2: Implement real thumbnail images where possible====

Currently we show images based on the mimetype of the file. For images, we should generate and cache small, efficient thumbnail images of the file for viewing in the file picker via lazy-loading.

Along with this, we should increase the length of pages as much as possible and reduce the number of pages. Scrolling works better than paging.

See: MDL-23044

====Solution C3: Add better CSS/renderers so themes can style it better====

====Solution C4: Add better descriptions/help for options====

Options all need help icons with translated popup help. "linking files" needs to be better explained.

====Solution C5: Simplify "Server Files"====

Server files can be made simpler.

# Only show courses that you have access to (can ignore categories, make it more like My Courses)
# Don't even show folders that are empty
# Remove some of the levels that are not needed, eg see MDL-27236
# Add support for all core modules, and add docs for the callback to help 3rd party authors (MDL-31675)

===Problem D: File area management===

====Solution D1: A dialog in the HTML editor to manage embedded files directly====

We need a way to edit the filearea that is associated with a HTML text. We currently do have one for non-Javascript users but it's never seen. We need a proper one available in the HTML editor, probably accessed as a popup dialog from a button with a yellow folder on it. Warnings need to be shown to the effect that renaming or removing files can break the HTML text.

====Solution D2: Add the ability to "replace" files.====

When a file is added to the file area with the same name as one that exists, a dialog should be shown allowing the user to "replace the existing file" or "rename the new file". The dialog should also indicate how many "[[Improved_support_for_external_File_content|linked copies]]" will be affected, if that is the case.

"Replace" means that the old file record is updated with the new content (perhaps with a version increment?) - this means that any LINKS to that file are retained, and it becomes possible to update many copies at once. This needs to be a new function in the file API.

==See also==

*[[Talk:Files usability 2.3]]

Profiling PHP

2012-11-07T02:33:54Z

Nicolasconnault:

PHP has two significant profilers. One is [http://www.xdebug.org/docs/profiler XDebug]. Tthis is well known and understood and its trace output is supported by tools like [http://kcachegrind.sourceforge.net/html/Home.html KCachegrind]. The other is [http://pecl.php.net/package/xhprof xhprof], a profiler released by facebook's engineering team, designed for capturing profile traces on live servers.

==Xdebug==

[http://xdebug.org/docs/profiler Xdebug] is a powerful PHP debugging tool. The first release of Xdebug was in 2002, since that it keeps growing and remains popular among PHP developers. Among its major features are stack and function tracing, code coverage analysis, remote debugging and scripts profiling. As the page topic suggests, we will focus on its profiling feature, which provides developer with detailed information about the script performance, helps identifying which parts of the code are slow. Collected information is being stored in cachegrind compatible file and can be analysed using one of external tools, such as [http://kcachegrind.sourceforge.net/html/Home.html KCachegrind], [http://sourceforge.net/projects/wincachegrind/ WinCacheGrind], [http://code.google.com/p/xdebugtoolkit/ xdebugtoolkit] or web-based analyser [https://github.com/jokkedk/webgrind#readme Webgrind]. Xdebug is simple to install and operate, it does not require code changes.

===Installing Xdebug extension===

The first step that has to be done is installing Xdebug extension. This procedure depends on the OS you are using, but general idea is to obtain Xdebug php extension and specify full path to it using ''zend_extension'' setting in ''php.inf'' file. Official [http://www.xdebug.org/docs/install Xdebug installation documentation] explains its installation on Windows, installing through PEAR/PECL and compiling from source.
Xdebug has been packaged for many Linux distributions, so it can be installed using corresponding package management tool. On Debian or Ubuntu, for example one would need to execute:

# apt-get install php5-xdebug

This will put ''xdebug.so'' in default php modules directory and create ''/etc/php5/conf.d/xdebug.ini'' file with single line:

zend_extension=/usr/lib/php5/20090626/xdebug.so

Note that this is equal to specifying the same line in ''php.inf'', example above just reflects split php configuration.

Once the Xdebug extension is installed and specified in php configuration, one may restart the webserver and information about Xdebug should appear in ''phpinfo()'' function output. If not, make sure that ''zend_extension'' line is not commented out, extension file exists in specified location and refer to webserver logs for more details.

===Configuring Xdebug Profiler===

When Xdebug extension is installed, it is time to configure profiling functionality. There are number of parameters related to profiling, all of them start with ''xdebug.profiler_'' prefix. First of all, profiler should be enabled. There are two ways of doing it. One way is keeping it always enabled, so profiling information will be generated on every page request:

xdebug.profiler_enable=1

Another way is making Xdebug writing profiling information on demand by triggering it with GET/POST or COOKIE variable named ''XDEBUG_PROFILE'':

xdebug.profiler_enable_trigger = 1

This option is preferable for several reasons: profiling data files are relatively large especially on complex scripts and you may run out of disk-space pretty quick, it allows generating profiling information only when you need it, thus it is easier to find the generated file in output directory, finally, on demand profiling can be done on production servers, though it is not recommended. If you have enabled ''xdebug.profiler_enable_trigger'' option, make sure that ''xdebug.profiler_enable'' is disabled, otherwise this will lead to dump file being generated on each request.

Whatever method of profiling enabling you have chosen, profiling data files will be generated on each request (or request with a trigger parameter) in directory specified with ''xdebug.profiler_output_dir'' directive. By default is it set to ''/tmp'', but you may change it to any more suitable location.

xdebug.profiler_output_dir=/tmp

Generated file will be named in accordance with ''xdebug.profiler_output_name'' setting. This setting can handle some specifiers and use them in the file name. Default name pattern is ''cachegrind.out.%p''; in the actual file name %p will be replaced with process ID value. The fill list of specifier can be found [http://www.xdebug.org/docs/all_settings#trace_output_name here]. More intuitive naming is recommended, so that it is easier to find the file you have just generated in the bunch of others:

xdebug.profiler_output_name=cachegrind.out.%R.%t

With this naming pattern, timestamp and script name will be reflected in the file name.

===Profiling a page===

When you are done with configuration, it is time to test it. First of all, the webserver has to be restarted, so that the new config will come into effect. Now assuming that Xdebug was configured to use a trigger for script profiling, open any php page on your server in your browser having added ''XDEBUG_PROFILE'' parameter to URL string:

<nowiki>http://servername/moodle2/index.php?XDEBUG_PROFILE</nowiki>

or if it already has some parameters, just add our trigger to the URL end:

<nowiki>http://servername/moodle2/mod/forum/view.php?id=5&XDEBUG_PROFILE</nowiki>

As a result, the new file should be generated in directory you specified with ''xdebug.profiler_output_dir'' directive:

cachegrind.out._moodle2_mod_forum_view_php.1289838411
cachegrind.out._moodle2_index_php.1289837892

Triggering profiling with POST requests or AJAX queries is also possible without code changes. [https://addons.mozilla.org/en-US/firefox/addon/58688/ Easy Xdebug] plugin for FireFox has profiling toggle button that inserts XDEBUG_PROFILE variable into cookie data, thus making profiling enabled for as long as you wish for all requests. Similar plugins exist for [https://chrome.google.com/extensions/detail/eadndfjplgieldjbigjakmdgkmoaaaoc Chrome] and [https://github.com/benmatselby/xdebug-toggler Safari] browsers.

===Analyzing Xdebug profiling files===

As it was pointed out earlier, profiling data is recoded in cachegrind format, so it can be analysed using one of external tools, such as [http://kcachegrind.sourceforge.net/html/Home.html KCachegrind], [http://sourceforge.net/projects/wincachegrind/ WinCacheGrind], [http://code.google.com/p/xdebugtoolkit/ xdebugtoolkit] or web-based analyser [https://github.com/jokkedk/webgrind#readme Webgrind]. Using these tools is pretty simple. I prefer KCachegrind which has a feature to show the matching code if web-server is run on the same box. Xdebug profiler documentation page has a [http://xdebug.org/docs/profiler#misc section] about KCachegrind that worth reading for everyone who starts using KCachegrind.

===Quick summary===

1. Install XDebug extension on your server.

2. Add something like this to your php.ini file:
zend_extension = /usr/lib/php5/20090626/xdebug.so
xdebug.profiler_enable = 0
xdebug.profiler_enable_trigger = 1
xdebug.profiler_output_dir = /var/tmp
xdebug.profiler_output_name = cachegrind.out.%R.%t
or add something like this to your .htaccess file
php_flag xdebug.profiler_enable off
php_flag xdebug.profiler_enable_trigger on
php_value xdebug.profiler_output_dir /var/tmp
php_value xdebug.profiler_output_name cachegrind.out.%R.%t

3. When you want to profile a page, add <tt>&XDEBUG_PROFILE</tt> to the end of the URL.

4. Open the <tt>cachegrind.out....</tt> file that is generated with one of the tools mentioned above.

==XHProf==

Compared to XDebug, XHProf aims to have the minimum impact on execution times and require relatively little space to store a trace, so you can run it live without a noticeable impact on users and without filling disks. The trade off with XHProf is in ''slightly'' less detail and a trace format that needs its own GUI to visualize (which ships with XHProf). The reason you'd want to profile in a live environments (vs. on development) is certain categories of problem may only been seen live, e.g. (data related) what happens when the user table grows 100 times, the impact on "login.php" or (service related) server to server HTTP requests. Did a presentation once [https://docs.google.com/present/view?id=dcbkgbgf_45fbg3rnmk XHProf - Facebook's PHP profiler] which explains in more detail - Penny saw the talk which is how I ended up writing this.

[[Setting up xhprof on Moodle]]

==See also==

* [http://moodle.org/mod/forum/discuss.php?d=162045 Forum thread about profiling Moodle 2.0]
XHProf articles:
* [https://docs.google.com/present/view?id=dcbkgbgf_45fbg3rnmk& Presentation about XHProf]
* [http://techportal.ibuildings.com/2009/12/01/profiling-with-xhprof/ Profiling with XHProf]
* [http://www.open.ac.uk/blogs/XHProf/?page_id=46 XHProf – Profiling and Reporting] from Moodle perspective written by [http://moodle.org/user/view.php?id=264538&course=5 James Brisland]
Xdebug articles:
* [http://devzone.zend.com/article/2803-Introducing-xdebug Introducing xdebug]
* [http://blog.teamlazerbeez.com/2010/05/04/xdebug-quickstart-profiling-in-php/ Xdebug Quickstart: Profiling in PHP]

XMLDB Creating new DDL functions

2012-11-07T02:33:05Z

Nicolasconnault: /* The example, explained */

{{Moodle 2.0}}[[XMLDB Documentation|XMLDB Documentation]] > [[XMLDB roadmap|Roadmap]] > XMLDB Creating new DDL functions ----__NOTOC__

'''Important note:''' All the functions showed in this page are for use in '''Moodle 2.0 upwards''', where we changed the [[DB layer 2.0|DB layer]] to support some new features. If you need information for previous Moodle version, take a look to the [[XMLDB creating new DDL functions - pre 2.0|pre 2.0]] page.

== Justification ==

Once the [[XMLDB Defining one XML structure|XMLDB Structure]] has been well defined and we are able to abstract any DB model with it, it's time to build one group of functions that will create the needed DB objects based in the information supplied by such XML structure. All those functions will use the underlying XMLB objects (XMLDBTable, XMLDBField, XMLDBKey, XMLDBIndex) in order to keep the level of abstraction across them.

The objectives to be supplied by these functions are:

* Be used by the '''installation''' process, replacing the old *.sql usage, to create all the needed DB objects.
* Be used by the '''upgrade''' process, in the new upgrade.php script, to handle all the DB objects.

Although initially it wasn't completely decided if all those XMLDB objects were going to be used by the DDL functions, or we were going to create a bunch of new functions, completely independent from the XMLDB schema, finally we decided to use the previously created object, mainly because:

* If we have some objects representing tables, fields and so on, it hasn't too much sense to build new functions requiring the same type of objects as parameters and not to use them.
* Any change in the XMLDB objects will be immediately available to the DDL functions (one new column type...).
* Code inside the DDL functions will be pretty simple because all the SQL code generation will be the responsibility of the XMLDB classes themselves.
* By using the XMLDB objects, the XMLDB Editor (the tool to edit XMLDB structures easily) could be improved in order to generate automatically the needed PHP code to be used by the upgrade.php scripts. Just select one object (table/field/index/key), one action to perform (create/drop/rename/alter) and, wow!, you will obtain all the PHP code to be pasted in the upgrade script. (coming soon) ;-)

The only drawback we have found is that upgrade code will be a bit longer, because it will need to include all the XMLDB objects creation and definition code. But, in the other hand, it will be an easily readable code.

== Implementation ==

=== Basic Concepts ===

All the functions will:

* accept one XMLDB objects (the one to be modified) as parameter.
* perform all the possible checks before executing any SQL command against DB.
* return true/false on success/error (the XMLDB object will contain extra info on error, available with the XMLDBObject->getError() function).
* output debug info if enabled.

=== Handling XMLDB objects ===

==== Introduction ====

Before calling the DDL functions themselves, the proper XMLDB objects must be properly created and contain all the needed info in order to allow the functions to do their work. The basic code structure for any DDL operation should be:

# Creation of the XMLDB objects programatically.
# Invocation of the DDL function.
# Check for errors

==== Basic example ====

One short (hehe!) example of these steps could be the following PHP lines, used to create a simple table with one primary key, one foreign key and one index:

<code php>
$field1 = new xmldb_field('id');
$field1->set_attributes(XMLDB_TYPE_INTEGER, '10', XMLDB_UNSIGNED, XMLDB_NOTNULL, XMLDB_SEQUENCE, [null, null,] null, null); // [XMLDB_ENUM, null,] Moodle 2.x deprecated
$field2 = new xmldb_field('name');
$field2->set_attributes(XMLDB_TYPE_CHAR, '255', null, XMLDB_NOTNULL, null, [null, null,] 'default name', 'id'); // [XMLDB_ENUM, null,] Moodle 2.x deprecated
$field3 = new xmldb_field('course');
$field3->set_attributes(XMLDB_TYPE_INTEGER, '10', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, [null, null,] null, 'name'); // [XMLDB_ENUM, null,] Moodle 2.x deprecated
$field4 = new xmldb_field('type');
$field4->set_attributes(XMLDB_TYPE_CHAR, '20', null, XMLDB_NOTNULL, null, [XMLDB_ENUM, array('type1', 'type2', 'type3'),] 'type1', 'course'); // [XMLDB_ENUM, null,] Moodle 2.x deprecated
$field5 = new xmldb_field('summary');
$field5->set_attributes(XMLDB_TYPE_TEXT, 'medium', null, null, null, [null, null,] null, 'type'); // [XMLDB_ENUM, null,] Moodle 2.x deprecated
$key1 = xmldb_key('primary');
$key1->set_attributes(XMLDB_KEY_PRIMARY, array('id'), null, null);
$key2 = xmldb_key('foreignkey1');
$key2->set_attributes(XMLDB_KEY_FOREIGN, array('courseid'), 'course', array('id'));

$index1 = xmldb_index('type');
$index1->set_attributes(XMLDB_INDEX_NOTUNIQUE, array('type'));

$table = new xmldb_table('my_first_xmldb_table');
$table->addField($field1);
$table->addField($field2);
$table->addField($field3);
$table->addField($field4);
$table->addField($field5);

$table->addKey($key1);
$table->addKey($key2);

$table->addIndex($index1);

$status = $dbman->create_table($table);
</code>

First of all, don't panic!, the code above can be easily reduced to, exactly, 10 lines, but in order to explain it with some detail we have posted here the long version. ;-) Also, don't forget that one of the upcoming features of the use of the XMLDB objects will be the '''ability of the XMLDB Editor to generate all this PHP code''' automatically for you.

==== The example, explained ====

Lets start with the very two first lines:
<code php>
$field1 = new xmldb_field('id');
$field1->set_attributes(XMLDB_TYPE_INTEGER, '10', XMLDB_UNSIGNED, XMLDB_NOTNULL, XMLDB_SEQUENCE, [null, null,] null, null); // [XMLDB_ENUM, null,] Moodle 2.x deprecated
</code>

In the first line we create a new field, called "id" (that will be the name of the column in the table, so do forget to follow the [[XMLDB Defining one XML structure#Conventions|XMLDB naming conventions]] and the [[Database|coding guidelines]].

In the second line we define all the attributes of the field with a simple function call. The list of parameters is:

# '''Column Type:''' Can be one of these: XMLDB_TYPE_INTEGER, XMLDB_TYPE_NUMBER, XMLDB_TYPE_CHAR, XMLDB_TYPE_TEXT, XMLDB_TYPE_BINARY. Note that XMLDB internals support other column types but they are only for compatibility with some special tables. Moodle shouldn't use anything out from the list above.
# '''Column precision:''' Its length for INTEGERS and CHARS, two comma-separated numbers (total length and number of decimal positions) for NUMBERS and one of this: "small", "medium", "big, for both TEXTS and BINARIES.
# '''Unsigned:''' To specify if the numeric field will be unsigned, we'll use the XMLDB_UNSIGNED constant. If signed, we'll pass null.
# '''Not Null:''' To specify if the field will be not null, we'll use the XMLDB_NOTNULL constant. If nullable, we'll pass null.
# '''Sequence:''' To specify if the field will be a sequence (or auto-numeric, or auto-incremented, or whatever you call it), we'll use the XMLDB_SEQUENCE constant. If not, we'll pass null.
# '''Enum:''' To specify if the field only will contain a limited number of possible values, we'll use the XMLDB_ENUM constant. If not, we'll pass null. // Moodle 2.0 deprecated
# '''Enum values:''' If the field has been defined as XMLDB_ENUM, this paramenter will have one array containing all the possible values for the field. Else, null. // Moodle 2.0 deprecated
# '''Default value:''' If the field has some meaningful default value to be defined this parameter will contain it. Else, null.
# '''After-field:''' If you want to enforce the field to be created after some other exact column in the DB, this parameter will allow you to do so. Note that, if not specified, every added field is created after the latest one so, in this example we could not define it at all. We'll use null once again if undefined.
So, the lines of code above are creating one Field, named "id", that will be an integer of 10 digits, not null and auto-numeric. Let's see the next fields:

<code php>
$field2 = new xmldb_field('name');
$field2->set_attributes(XMLDB_TYPE_CHAR, '255', null, XMLDB_NOTNULL, null, [null, null,] 'default name', 'id'); // [XMLDB_ENUM, Enum values,] Moodle 2.x deprecated
</code>

Here we are creating one new field, called "name", defined as one char with maximum length of 255cc, not null, with one default value ("default name") and to be created after the "id" field (note again that, to build tables, this order isn't useful at all and the order of adding the fields to the table will be used).

Lets examine the next one:

<code php>
$field3 = new xmldb_field('course');
$field3->set_attributes(XMLDB_TYPE_INTEGER, '10', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, [null, null,] null, 'name'); // [XMLDB_ENUM, Enum values,] Moodle 2.x deprecated
</code>
Another new field, called "course", integer with a maximum length of 10, unsigned and not null (forget the 'name' value, to define '''after-field''' info as we said some lines above).

Another one field:

<code php>
$field4 = new xmldb_field('type');
$field4->set_attributes(XMLDB_TYPE_CHAR, '20', null, XMLDB_NOTNULL, null, [XMLDB_ENUM, array('type1', 'type2', 'type3'),] 'type1', 'course'); // [XMLDB_ENUM, Enum values,] Moodle 2.x deprecated
</code>

This field will be called "type", char(20), not null, will have three possible values ("type1", "type2" and "type3") and its default value will be "type1".

And the final field in our example:

<code php>
$field5 = new xmldb_field('summary');
$field5->set_attributes(XMLDB_TYPE_TEXT, 'medium', null, null, null, [null, null,] null, 'type');
</code>

That will be a field name "summary" of type text with a "medium" length.

Also note that it isn't mandatory to specify all those "null" parameters and, starting from the right, we can safely avoid them, so the last field we have seen could be (if we ignore, once more, the '''after-field''' parameter:

<code php>
$field5->set_attributes(XMLDB_TYPE_TEXT, 'medium');
</code>

Now, we'll analyse the creation of keys. The first key specified in our example is:

<code php>
$key1 = new xmldb_key('primary');
$key1->set_atrributes(XMLDB_KEY_PRIMARY, array('id'), null, null);
</code>

With the first line, we create an index named "primary". It's important to note that, whereas field names specified in the previous code is important because it's going to be the name of the fields in the DB, the names specified here aren't important at all, mainly, because of [[XMLDB key and index naming]] specs, so the keys and indexes created will be automatically named following those rules. Anyway, in the XMLDB files we use to call "primary" to the primary key and to concatenate the name of the fields in the key/index separated by "-" as their official name. But here it isn't important.

The second line completely defines the key. Attributes are:

# '''Key Type:''' Can be one of these: XMLDB_KEY_PRIMARY, XMLDB_KEY_UNIQUE and XMLDB_KEY_FOREIGN that are the basic constraint types for our relational DB model. It's important to note that all the keys above will have one index created for them automatically so, when you define any Key, you haven't to define any index with the same fields at all. XMLDB will do it for you. More yet, for now, Foreign Keys won't be enforced (just the underlying indexes will be created) because before enabling them a lot of changes need to be performed within Moodle processes. But we want to have all those relations defined since the beginning of XMLDB. It will allow us to move quickly to a pure relational model.
# '''List of fields:''' An array containing the names of the fields that will be part of the key (and the underlying index).
# '''Reference table:''' Exclusively for Foreign Keys, the table where the fields defined in the previous parameter are pointing to.
# '''Reference fields:''' Exclusively for Foreign Keys, the list of fields in the reference table that must match with the list of fields in the own table. Please note that, those "reference fields" must be defined as primary or unique key in the reference table. Relational rules, you know. So avoid pointing to fields not satisfying this condition completely!

With all this info, we know that we are going to create one primary key with the field "id". Remember that XMLDB will set the correct name for that key.

The second index in our example says:

<code php>
$key2 = new xmldb_key('foreignkey1');
$key2->set_attributes(XMLDB_KEY_FOREIGN, array('courseid'), 'course', array('id'));
</code>

Here we are creating one more key, of type foreign key, with the field "course" pointing to the "id" field of the "course" table. Once more, the name isn't important at all.

And finally, we arrive to the indexes. Don't forget that all the previously defined keys will generate one underlying index with the fields specified so, in this sections we only have to define some other combinations of fields that are used often by SQL statements. By providing the correct indexes we'll get big speed improvements. But they must be correct. It's absolutely wrong to "index everything" without knowing what is being done. Don't forget it!

In our example we have this lines of code:

<code php>
$index1 = new xmldb_index('type');
$index1->set_attributes(XMLDB_INDEX_NOTUNIQUE, array('type'));
</code>

In the first line we create the new index object. Remember, that the name provided here isn't the name of the index in the RDBMS, [[XMLDB key and index naming]] will define it automatically.

In the second line we specify:

# '''Index Type:''' that can be XMLDB_INDEX_NOTUNIQUE (that is pretty equivalent to null, the default) or XMLDB_INDEX_UNIQUE depending if the list of fields defined in the previous parameter allows duplicate tuples or no.
# '''List of fields:''' An array containing the names of the fields that will be part of the index.

So, in the example, we are creating one non unique index with the field called "type".

With this we've seen all the individual objects that conforms one table structure. Now we are going all these object to our new table so code says:

<code php>
$table = new xmldb_table('my_first_xmldb_table');
$table->addField($field1);
$table->addField($field2);
$table->addField($field3);
$table->addField($field4);
$table->addField($field5);

$table->addKey($key1);
$table->addKey($key2);

$table->addIndex($index1);
</code>

With this lines we are simply creating one new table, called "my_first_xmldb_table", whose name must follow the [[XMLDB Defining one XML structure#Conventions|XMLDB naming conventions]] and the [[Database|coding guidelines]]. Then all the previously defined fields, keys and indexes are added to the table. Point.

And the final line of our code is:

<code php>
$status = $dbman->create_table($table);
</code>

With this line, we'll create the DB table, with all the fields/keys/indexes specified with all the specs defined in the previous lines, with the correct prefix, proper object naming and particularities for each different RDBMS. This function call will return true/false, depending if the execution of the needed SQL commands has ended Ok or no.

Wow, at last, we end!!

==== Reduced (and recommended) example ====

All the lines in the example above have been really good to explain how to create any XMLDBField, XMLDBKey, XMLDBIndex and XMLDBTable structures from PHP code but we must recognise that it's a bit awful in terms of readability and length. So, for the creation of tables, we can use the following code, that is a complete replacement for the previous one:

<code php>
$table = new xmldb_table('my_first_xmldb_table');

$table->add_field('id', XMLDB_TYPE_INTEGER, '10', XMLDB_UNSIGNED, XMLDB_NOTNULL, XMLDB_SEQUENCE, null, null, null);
$table->add_field('name', XMLDB_TYPE_CHAR, '255', null, XMLDB_NOTNULL, null, null, null, 'default name');
$table->add_field('course', XMLDB_TYPE_INTEGER, '10', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, null, null, null);
$table->add_field('type', XMLDB_TYPE_CHAR, '20', null, XMLDB_NOTNULL, null, XMLDB_ENUM, array('type1', 'type2', 'type3'), 'type1');
$table->add_field('summary', XMLDB_TYPE_TEXT, 'medium', null, null, null, null, null, null);

$table->add_key('primary', XMLDB_KEY_PRIMARY, array('id'), null, null);
$table->add_key('foreignkey1', XMLDB_KEY_FOREIGN, array('courseid'), 'course', array('id'));

$table->add_index('type', XMLDB_INDEX_NOTUNIQUE, array('type'));

$status = $dbman->create_table($table);
</code>

Better, isn't it? ;-)

All the documentation in the previous complete example continues being 100% valid here. Just note that, when using this syntax, we have one more field, exactly '''the first one''', that must be used to specify the name of the field/key/index being added. The rest is exactly the same!

=== Integration with the XMLDB Editor ===

Now you should know a bit more about how to create tables via PHP under the new XMLDB schema. It was really important to know about it because, in the process, you've seen how to create fields, keys and indexes, plus some extra notions about the whole thing.

Also, the creation of tables is, with difference, the most difficult operation (in terms of PHP generated) that you will find under all the new DDL functions. Other operations like rename, drop, alter will be really easier to use. Trying to help you a bit in the PHP generation, if you use the XMLDB Editor to design and create your DB structures, you will be able to obtain all the code needed to perform different DDL actions automatically.

Just go to the table/field/key/index you are modifying and, after performing the desired changes, press the "PHP Code" link and it will show you one new page with all (practically) the options available. Just select the desired one and the required PHP will appear in seconds

Such code can be directly used by your upgrade scripts (by modifying some minor bits here and there) improving the DB experience and reducing the risk of errors a lot.

Also, it's highly recommended to use such utility to understand better how the PHP code works, like an online tutor. Enjoy it!

== See also ==

* [[DDL functions|DDL functions]]: To get access to the updated documentation about the functions available to modify the DB objects.
* [[XMLDB Defining one XML structure|XML structure]]: To know a bit more about the internal XML structure used to describe all the DB objects using one neutral language.
* [[XMLDB List of DDL functions to create|List of functions to create]]: The list of functions to be created from scratch. Used to follow the progress and its status.

[[Category:XMLDB]]

Course formats 2

2012-11-07T02:29:18Z

Nicolasconnault: /* Backward compartibility */

{{Infobox Project
|name = Course formats refactoring
|state = FINAL DISCUSSION OF SPECIFICATION
|tracker = MDL-35218
|assignee = [[User:Marina Glancy|Marina Glancy]]
|discussion = http://moodle.org/mod/forum/discuss.php?d=212405
}}

{{Moodle 2.4}}

We will refactor the course formats to support a proper object-oriented design and flexibility
==Database changes==
* change course.format from varchar(10) to varchar(21)
* add table course_format_options that will store format-specific options for the whole course and for specific secions (fields: id, courseid, format, sectionid[optional], name, value)
* remove existing fields in table course: numsections, hiddensections, coursedisplay

==Object model==

Course formats must be classes inheriting base '''class format_base''' instead of the current collection of callbacks. (Although some callbacks will be converted to methods)

Method '''course_get_format($course)''' will return an instance of this class for the particular course. May be called with specific format but with empty course id (i.e. when course is being created)

===Class format_base===

{| class="nicetable"
|-
! method
! description
|-
| get_default_blocks()
| replaces config.php with $format[‘defaultblocks’]
|-
| course_format_options()
| definitions of the additional options that this course format uses for course
|-
| section_format_options()
| definitions of the additional options that this course format uses for section
|-
| edit_form_validation()
| performs additional validation for edit course form
|-
| page_set_course()
| is called from moodle_page::set_course() allowing course formats to run custom code at that point
|-
| page_set_cm()
| is called from moodle_page::set_cm()
|-
| output_course_header()
| displays the course-specific header. It will be included in all core themes, custom themes need to add support for it. Inside it should call function from renderer
|-
| output_course_footer()
| displays the course-specific footer
|-
| output_course_content_header()
| displays the course-specific header to be displayed in main content section (i.e. prev-next module navigation)
|-
| output_course_content_footer()
| displays the course-specific footer to be displayed in main content section (i.e. prev-next module navigation)
|-
| editsection_form()
| returns an instance of editsection_form (the format can overwrite this form)
|-
| is_section_current()
| replaces format_section_renderer_base::is_section_current()
|-
| get_section_name()
| is called from global function get_section_name()
|-
| uses_sections()
| is called from global function course_format_uses_sections()
|-
| supports_ajax()
| is called from global function course_format_ajax_support()
|-
| extend_course_navigation()
| replaces callback_FORMAT_load_content()
|-
| get_view_url()
| is called from course_get_url() and replaces callback_FORMAT_get_section_url()
|}

==Backward compartibility==

Define class format_legacy extends format_base that will call the existing callbacks and get blocks from config.php if format class is not defined (2.0-2.3 backward compartibility). Function course_get_format() will return instance of this class if the course format does not define its own class

==Course sections hierarchy==

Add support for nested course sections:
* avoid loops,
* store visibleold;
* Process moving, deleting sections;
* Make sure the hierarchy appears in navigation menu and breadcrumb;
* Make sure changing of availability rules for both parent and child sections works correctly together

Core formats will NOT support hierarchy, we just want to make sure that non-plugin code can deal with it

==Course add/edit form==

* When course is created/edited, the options specific for the format are displayed in separate form section and it dynamically changes when format is changed (with support of non-js mode). Each course format defines which display options it needs. For the standard weeks/topics formatd they are [numsections, hiddensections, coursedisplay], for scrom and social there are no options
* Make Course format selector on create/edit course page looking similar to "Add activity" with help text for each format

==Course sections management==

* ? Add events_triggers in functions that create/delete/hide/move course sections
* Refactor class editsection_form so it is easier to overwrite and implements functions set_data() and get_data() instead of pre/post processing data in editsection.php

==Add course formats as plugin to site administration==

Course formats are plugins in the code, but they are not handled as plugins in the administration. Replace course default settings by this page. Move page to plugins.

* option to enable/disable a course format
* each course format may have it's own configurable options such as default and/or sticky blocks, default settings, etc.

==Other changes related to course formats==

* Make sure backup/restore correctly works with sections hierarchy and new options. Also backup made in previous versions restores correctly in 2.4
* Make sure course format can influence navigation menu and breadcrumb. This probably will be done already by set_course/set_cm callbacks
* Course formats may want to extend course settings navigation. Implement additional callback or do it in set_course() ?
* Improvement: file_info (Server files repository) should list modules inside the course groupped by sections
* Describe in course formats dev documentation how formats can watch the events triggers

==Changes to course-related functions in 2.4==
(see MDL-35339)
* add function get_module_types_names() to replace $modnames and $modnamesplural in get_all_mods()
* add course_modinfo::get_used_module_types() to replace $modnamesused in get_all_mods()
* deprecate function get_all_mods(), change it's usage
* deprecate function get_all_sections()
* deprecate add_mod_to_section() and replace it with course_add_cm_to_section() to fix the mess in arguments

==Comments to the changes of the specification==

During actual development the specification was changed a little.
* table course_sections will not have additional fields 'parent' and 'visibilityold'. If course format wants to support hierarchy, they should be defined as additional format options. There will be no performance change if we add those fields to the course_sections table because the information about all sections is cached anyway in course.sectioncache and should be accessed only using get_fast_modinfo()
* there is no need in trigger 'course_format_changed' because there is already a trigger 'course_updated' and before it the format_base::update_course_format_options() is called with the before-update value of $course object
* field course.format has the length 21 because if format wants to define it's own tables the table name should start with 'format_FORMATNAME' and at the same time it's name should not be longer than 28 symbols. Therefore there is 21 char left for FORMATNAME
* function format_base::is_setup_completed() is not necessary because this functionality can be done in page_set_course() hook.

==Wishlist==

* Add field course_module.sortorder and deprecate course_section.sequence (not in 2.4!)

==Class course (for discussion, NOT for 2.4)==
There are number of course-related functions in the core with random names. The argument name/property 'section' is used for both {section}.id and {section}.section, sometimes even the same variable changes it's meaning. Some very important functions completely miss phpdocs.

Besides it will be more understandable for developers of modules and other plugins to relate to course object and not to course format (for example to get section name, etc.)

The proposal is:
* move code of all those functions into new class 'course'
* leave the functions themselves in course/deprecatedlib.php with developer warning and call to corresponding function from course class
* update usage of those functions in the core
* add function get_course() or course_get_course() to retrieve the cached instance of the course, make sure cache is emptied inside rebuid_course_cache()
* try to replace multiple similar queries $DB->get_record('course', array('id'=>$courseid)) in the core code

Source of course/lib.php: https://github.com/moodle/moodle/blob/master/course/lib.php

{| class="nicetable"
|-
! Existing function
! New function
|-
| get_fast_modinfo()
| ? course::get_modinfo()
|-
| get_array_of_activities()
| course::get_array_of_activities() [used only by get_fast_modinfo()]
|-
| course_set_marker()
| course::set_marker()
|-
| set_section_visible
| course::set_section_visible()
|-
| add_course_module()
| course::add_cm_raw() This function only creates an entry in table {course_module}
|-
| course_add_cm_to_section()
| course::cm_add_to_section()
|-
| -
| course::add_cm() calls previous two functions and rebuild_course_cache()
|-
| get_course_section()
| course::get_or_create_section() will return section_info
|-
| -
| course::get_section() will return section_info, alias to get_fast_modinfo()->get_section_info()
|-
| -
| course::get_sections() alias to get_fast_modinfo()->get_section_info_all()
|-
| set_coursemodule_groupmode()
| course::set_cm_groupmode()
|-
| set_coursemodule_idnumber()
| course::set_cm_idnumber()
|-
| set_coursemodule_visible()
| course::set_cm_visible()
|-
| delete_course_module()
| course::delete_cm_raw()
|-
| delete_mod_from_section()
| course::delete_cm_from_section()
|-
| -
| course::delete_cm() will call both previous functions
|-
| move_section_to()
| course::move_section(), also call rebuild_course_cache()
|-
| reorder_sections()
| course::reorder_sections(), also call rebuild_course_cache()
|-
| moveto_module()
| course::move_cm()
|-
| course_format_name()
| course::get_formatted_name()
|-
| get_section_name()
| format_base::get_section_name() with aliases: course::get_section_name() and section_info::get_name()
|-
| can_delete_course()
| course::can_delete()
|-
| create_course()
| course::create() [static]
|-
| update_course()
| course::update()
|-
| course_ajax_enabled()
| course::is_ajax_enabled()
|-
| include_course_ajax()
| course::include_ajax()
|-
| course_get_url()
| course::get_view_url()
|}

Other course-related functions in course/lib.php

* get_print_section_cm_text()
* print_section()
* print_section_add_menus()
* get_module_metadata()
* print_course
* make_editing_buttons()
* course_allowed_module()

Behat integration

2012-11-07T02:28:35Z

Nicolasconnault: /* Objective */

{{Work in progress}}

== Introduction ==

This page describes the internals of Behat and the integration with Moodle. For the functional description see https://docs.moodle.org/dev/Acceptance_testing.

Behat is a framework for behaviour driven development (BDD) allows us to specify Moodle functionalities (aka features) as a human-readable list of steps and parse this steps to execute actions to simulate user interaction, it executes the actions against a headless browsers (without javascript support, only curl-kind petitions) or automation tools like Selenium, which interacts with browsers and allows Javascript events simulation.

(This is not in standard Moodle yet: to play a bit with it now clone https://github.com/moodlehq/moodle-behat-features and follow the installation and usage instructions, you may need to hack a bit to pass all the tests, it depends on you Moodle site contens. Is an example of tool usage but not an example of good practices to create tests and specify fixtures)

== Objective ==
The aim of this integration is to allow Moodle components to have its own set of features and steps definitions, this allows BDD in Moodle and allows us to execute periodically the whole set of tests to detect regressions and test the Moodle features in different environments (browsers, DBs engines, web servers...).

== How Behat works ==
This section aims to explain the basics about BDD and Behat and a quick view of how Behat internally works from the CLI command execution to the results output.

Some terms used:
* '''Features''': Human-readable list of scenarios that describes a feature

@auth
'''Feature''': Login
In order to login
As a moodle user
I need to be able to validate the username and password against moodle

'''Scenario''': Login as an existing user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

'''Scenario''': Login as an unexisting user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

* '''Scenario''': Human-readable list of steps to describe an expected behaviour
'''Scenario''': Login as an existing user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"
* '''Steps''': Human-readable sentences that describes an action. There are 3 types of steps, "Given" describing the initial context, "When" the event that provokes a change and "Then" where the outcomes should be asserted.
I click on the "Add user" button
* '''Steps definitions''': PHP methods referenced by steps when matching it's regular expression. The @Given, @When and @Then tags are descriptive and they are not taken into account when matching steps with steps definitions. The regular expressions placeholders are returned to the PHP method as arguments so methods can use them to tell the browser which button (for example) they want to click.
/**
* @When /^I click on the "(.*)" button$/
*/
public function i_click_on_the_button($button) {
// Simulates the user interaction (see Mink description below for more info)
$this->getSession()->getPage()->pressButton($button);
}

* '''Behat''': PHP framework and CLI application that wraps the whole process of features files loading + features files parsing + execution of actions in the browser + results output (http://behat.org/)
* '''Gherkin''': Human-readable language used to define features that can be parsed and translated into PHP methods. For more info, it's the same language used by Cucumber, the BDD Ruby framework (https://github.com/cucumber/cucumber/wiki/Gherkin)
* '''Context''': In Behat scope a context is a PHP class that groups steps definitions (as methods)
* '''Mink''': Is the component which interacts with browsers, simulating a real user interaction. It allows us to write PHP code (or use the available PHP methods) to send petitions to the different browsers APIs through a common interface or extend it to allow browser-specific actions. The supported browsers includes Selenium, Selenium2, Sahi... http://mink.behat.org/
* '''Selenium 2''': Web browser automation tool, applications like Mink can communicate with it through a RESTful API (http://code.google.com/p/selenium/wiki/JsonWireProtocol) to execute actions simulating user interaction.

All this components are written in PHP, open sourced and packaged in a single and extensible framework.

=== Quick view of the whole process ===

# Behat CLI execution
#* Behat application initialization and loading of arguments (features files to execute, output format...)
#* Reads the Behat config file (browser servers are specified here)
#* Extensions overrides management
#* Gherkin initialization
# Features files selection
#* According to the arguments Gherkin looks for .features files
#** It can use different features loaders (single file, a directory, the default directory...)
#** The framework can be extended to allow multiple folders loading
# Features parsing (Gherkin)
#* Loops through the loaded features files looking for scenarios
#* Gets the list of steps of each scenario
#* There are hooks at different levels (http://docs.behat.org/guides/3.hooks.html)
# Steps parsing (Gherkin)
#* Gherkin looks in the available steps definitions for a regular expression that matches the step text
# Step definition execution
#* The step definition code is executed
#* Steps definitions most of the time uses the Mink component to communicate with the browser API sending petitions like "click on that button" or "go to XXX page"
# Scenario outcomes
#* The scenario counts as failed if an exception is thrown when executing a step definition (for example trying to click a non-existing button)
#* The scenario counts as passed if no exception is thrown during it's steps execution
# Finishing CLI execution
#* A summary with all the scenario results is displayed
#* It accepts different output formats (like JUnitXML) to it's execution in continuous integration systems (http://docs.behat.org/guides/6.cli.html#format-options)

== Moodle integration ==

It follows the approach chosen with PHPUnit:
* Moodle components (subsystems and plugins) can have a tests/behat/ folder
* The behat project is not included in Moodle codebase and has to be installed separately (https://github.com/dmonllao/behat-moodle/blob/master/README.md)
* The scenarios are executed in a test environment (the same test environment used to execute PHPUnit tests)
* The scenarios specifies their own fixtures and it's execution is isolated from other scenarios and features
* Moodle lists the features files and steps definitions of it's components in a config.yml file, similar to the phpunit.xml manifest, that is read by Behat

This tests can not be executed in production sites; before executing the tests the whole site switches to "test environment" and all the logged users are kicked out. This is required because Behat runs black box tests simulating user interaction, it accesses via URL to the site like an user does.

=== Admin tool "Acceptance testing" ===

There is an admin tool in admin/tool/behat/index.php (https://github.com/dmonllao/moodle/tree/MDL-35611_master/admin/tool/behat) to run and ease the creation of acceptance tests. All the features listed below can be executed through CLI and web although it's better to run the tests with CLI. You can:
# List the available steps (with an option to filter by keyword)
# Run the tests (with an option to filter by tag or to add extra behat command options) it also updates the config.yml file
* Also you can switch the real and test environments (uses $CFG->phpunit_prefix and $CFG->phpunit_dataroot instead of the regular $CFG->prefix and $CFG->dataroot) if you need to check something

=== Behat extension ===
The Behat framework is extended to load features and steps definitions from multiple folders (subsystems and plugins).

The basic Behat framework only allows one folder to look for features, we can set $CFG->dirroot as a single features project, but Behat will have a huge amount of work to do every time is executed to find where the features classes are. The basic framework has been extended to read the Moodle config.yml file, and with it's data, to load the features and steps definitions files spread along different Moodle components. (https://github.com/dmonllao/moodle-behat-extension)

Activity modules

2012-11-07T02:27:41Z

Nicolasconnault: /* view.php */

== Introduction ==

Activity modules reside in the '''/mod''' directory.

Each module is in a separate subdirectory and consists of a number of ''''mandatory files'''' and any other files the developer is going to use. The below image is an example of the certificate module's filestructure. Please note, any reference to <modname> in this documentation should be replaced by the name of your module.

Below is an example of the file structure for the certificate plugin.

[[File:Activities_file_structure_example.jpg]]

== Standard Files and their Functions ==

There are several files that are crucial to Moodle. These files are used to install your module and then integrate it into the Moodle system. Each file has a particular function, some of the files are not necessary and are only created when wanting to use the functionality it offers. Below are the list of most commonly used files.

=== Backup Folder ===

This is the location to place the files that define how your module is going to behave when a course backup or restore is performed. You may have added a lot of information to the database for a specific module that you do not wish to enter again when restoring a course, this is where you define what should be saved during a backup and how to then restore this information from the Moodle backup.

To read more on this please visit [[Backup_2.0_for_developers]] and [[Restore_2.0_for_developers]].

=== DB Folder ===

==== access.php ====

This is where you define what capabilities your plugin will create. Note, if you add new capabilities to this file after your plugin has been installed you will need to increase the version number in your version.php file (discussed later) in order for them to be installed.

An example of the file is below -

<code php>

$capabilities = array(

'mod/certificate:addinstance' => array(
'riskbitmask' => RISK_XSS,
'captype' => 'write',
'contextlevel' => CONTEXT_COURSE,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),
'clonepermissionsfrom' => 'moodle/course:manageactivities'
),
);

</code>

In Moodle 2.3 a new capability called 'addinstance' was added for all core modules. Moodle will look for this capability by searching for 'mod/<modname>:addinstance' and if it is not created then it assumed that the user does have this capability with a debug message being displayed that the capability is missing. To avoid this situation it is good to add this to your module. For further information on what each attribute in that capabilities array means visit [[NEWMODULE_Adding_capabilities]].

==== install.xml ====

This file is used on installation of your module. It includes the database tables and fields that your module will be creating. If your module does not require any new tables then this file is not necessary. In order to create this XML file please view [[XMLDB_editor]]. Please note, in the XML file the table names are listed without the config.php prefix, this is automatically used when creating the tables and does not need to be specified.

An example of this file is below -

<code php>
<?xml version="1.0" encoding="UTF-8" ?>
<XMLDB PATH="mod/certificate/db" VERSION="20120925" COMMENT="XMLDB file for Moodle mod/certificate"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../../lib/xmldb/xmldb.xsd"
>
<TABLES>
<TABLE NAME="certificate" COMMENT="Defines certificates" NEXT="certificate_issues">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="course"/>
<FIELD NAME="course" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="name"/>
<FIELD NAME="name" TYPE="char" LENGTH="255" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="course" NEXT="intro"/>
<FIELD NAME="intro" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="name" NEXT="introformat"/>
<FIELD NAME="introformat" TYPE="int" LENGTH="4" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" PREVIOUS="intro" NEXT="emailteachers"/>
<FIELD NAME="emailteachers" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="introformat" NEXT="emailothers"/>
<FIELD NAME="emailothers" TYPE="text" LENGTH="small" NOTNULL="false" SEQUENCE="false" ENUM="false" PREVIOUS="emailteachers" NEXT="savecert"/>
<FIELD NAME="savecert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="emailothers" NEXT="reportcert"/>
<FIELD NAME="reportcert" TYPE="int" LENGTH="1" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="savecert" NEXT="delivery"/>
<FIELD NAME="delivery" TYPE="int" LENGTH="3" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="reportcert" NEXT="requiredtime"/>
<FIELD NAME="requiredtime" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="delivery" NEXT="type"/>
<FIELD NAME="type" TYPE="char" LENGTH="50" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="requiredtime" NEXT="orientation"/>
<FIELD NAME="orientation" TYPE="char" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="type" NEXT="width"/>
<FIELD NAME="width" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="orientation" NEXT="height"/>
<FIELD NAME="height" TYPE="int" LENGTH="10" NOTNULL="true" SEQUENCE="false" ENUM="false" PREVIOUS="width" NEXT="backgroundimage"/>
<FIELD NAME="backgroundimage" TYPE="char" LENGTH="255" NOTNULL="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="height" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="backgroundimage" NEXT="timemodified"/>
<FIELD NAME="timemodified" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="timecreated"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate"/>
</KEYS>
</TABLE>
<TABLE NAME="certificate_issues" COMMENT="Info about issued certificates" PREVIOUS="certificate">
<FIELDS>
<FIELD NAME="id" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" SEQUENCE="true" ENUM="false" NEXT="userid"/>
<FIELD NAME="userid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="id" NEXT="certificateid"/>
<FIELD NAME="certificateid" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="userid" NEXT="timecreated"/>
<FIELD NAME="timecreated" TYPE="int" LENGTH="10" NOTNULL="true" UNSIGNED="true" DEFAULT="0" SEQUENCE="false" ENUM="false" PREVIOUS="certificateid"/>
</FIELDS>
<KEYS>
<KEY NAME="primary" TYPE="primary" FIELDS="id" COMMENT="Primary key for certificate_issues" NEXT="certificate"/>
<KEY NAME="certificate" TYPE="foreign" FIELDS="certificateid" REFTABLE="certificate" REFFIELDS="id" PREVIOUS="primary"/>
</KEYS>
</TABLE>
</TABLES>
</XMLDB>
</code>

The above example contains the structure of the table certificate and certificate_issues. Each table, field and key lists what element is before and after it (if there are any present). This is automatically created by the [[XMLDB_editor]]. Your module should always have a table with the same name as the module with the fields id, name and course as shown above.

==== upgrade.php ====

This file handles upgrading the module to match the latest version. After creating a module and using it extensively on your site (and others) you may want to extend the functionality of your module. Using the certificate example, a suggestion was made that a unique code could be generated for each certificate issued and displayed if a setting was selected. This requires two new database fields, one to store whether the user has chosen to display the code on the certificate and another to store the actual code. This is where the upgrade.php script becomes used. The install.xml file is only executed once, that is when your module is first installed, so adding these two extra columns to this file does not change the database structure for users who have already installed the module. So, to perform this upgrade you need to do three things.

1. Add the new columns to the install.xml file so that any users who install the module after this point are given the new table structure. 
2. Add the instructions for the upgrade.php files. 
3. Update the version number in your version.php file. 

In this example we are only adding two new columns to the database, so we can use the [[XMLDB_editor]] to change the install.xml file AND create the upgrade path.

An example of the upgrade.php file is as follows -

<code php>
function xmldb_certificate_upgrade($oldversion=0) {
if ($oldversion < 2012091800) {
// Add new fields to certificate table.
$table = new xmldb_table('certificate');
$field = new xmldb_field('showcode');
$field->set_attributes(XMLDB_TYPE_INTEGER, '1', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'savecert');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}
// Add new fields to certificate_issues table.
$table = new xmldb_table('certificate_issues');
$field = new xmldb_field('code');
$field->set_attributes(XMLDB_TYPE_CHAR, '50', null, null, null, null, 'certificateid');
if (!$dbman->field_exists($table, $field)) {
$dbman->add_field($table, $field);
}

// Certificate savepoint reached.
upgrade_mod_savepoint(true, 2012091800, 'certificate');
}
}
</code>

Whenever you change the version in your version.php module Moodle will look to see if anything needs to be done. The version that is stored in the database is passed to the xmldb_<modname>_upgrade function as the variable $oldversion in this case. In this example lets say that the initial version was 2012091600, since this is less than 2012091800 (the new value we put in the version.php file) we will execute the code in the if statement which will then update the version stored in the database meaning this if statement is never executed again. For more extensive details on this please see [[Upgrade_API]].

=== Lang Folder ===

This is where you store any strings you are going to use in your plugin. Each language has a specific folder that needs to be created in order for it to be used with your module. In this case we are going to use the English language (since unfortunately it is the only one I know). A folder called en is created in your lang folder that contains a file called <modname>.php that lists the translations of your string. For example, your module may have a setting called 'User preferences', rather than hard coding this term in your form, you use a placeholder that will then retrieve the appropriate string depending on the language being used on your Moodle site. There is one mandatory placeholder for modules called 'pluginname' that Moodle will use when listing this module as an option to add to a course and other various pages. To keep with Moodle standards you should order your strings alphabetically by the placeholder name.

<code php>
$string['pluginname'] = 'Certificate';
$string['userpreferences'] = 'User preferences';
</code>

If you wanted to add the French translation you would create a folder called fr and add the file <modname>.php to it.

<code php>
$string['pluginname'] = 'Certificat';
$string['userpreferences'] = 'Préférences d\'utilisateur';
</code>

Now, when using the string 'User preferences' we will use the Moodle function get_string instead, which will get the appropriate string depending on the language being used.

<code php>
get_string('userpreferences', '<modname>');
</code>

=== Pix folder ===

Here you simply store the icon you wish Moodle to display next to the name of your module. The name of the file should be icon.gif and is displayed with the resolution of 64 * 64. Feel free to use this folder to store other pictures you may use.

=== lib.php ===

The list of functions that are possible to override in the lib.php are listed here [[NEWMODULE_Documentation#lib.php]]. The essential ones are listed below

<code php>
function certificate_add_instance($certificate);
function certificate_update_instance($certificate);
function certificate_delete_instance($id);
</code>

The <modname>_add_instance function is passed the variables from the mod_form.php file (discussed later) as an object when you first create an activity and click submit. This is where you can take that data, do what you want with it and then insert it into the database if you wish. This is only called once when the module instance is first created, so this is where you should place the logic to add the activity. 
The <modname>_update_instance function is passed the variables from the mod_form.php file as an object whenever you update an activity and click submit. The id of the instance you are editing is passed as the attribute instance and can be used to edit any existing values in the database for that instance. 
The <modname>_delete_instance function is passed the id of your module which you can use to delete the records from any database tables associated with that id. For example, in the certificate module the id in the certificate table is passed, and then used to delete the certificate from the database, any issues of this certificate and any files associated with it on the filesystem.

=== mod_form.php ===

This file is used when adding/editing a module to a course. It contains the elements that will be displayed on the form responsible for creating/installing an instance of your module. The class in the file should be called mod_<modname>_mod_form.

<code php>
if (!defined('MOODLE_INTERNAL')) {
die('Direct access to this script is forbidden.'); /// It must be included from a Moodle page
}

require_once($CFG->dirroot.'/course/moodleform_mod.php');
require_once($CFG->dirroot.'/mod/certificate/lib.php');

class mod_certificate_mod_form extends moodleform_mod {

function definition() {
global $CFG, $DB, $OUTPUT;

$mform =& $this->_form;

$mform->addElement('text', 'name', get_string('certificatename', 'certificate'), array('size'=>'64'));
$mform->setType('name', PARAM_TEXT);
$mform->addRule('name', null, 'required', null, 'client');

$ynoptions = array(0 => get_string('no'),
1 => get_string('yes'));
$mform->addElement('select', 'usecode', get_string('usecode', 'certificate'), $ynoptions);
$mform->setDefault('usecode', 0);
$mform->addHelpButton('usecode', 'usecode', 'certificate');

$this->standard_coursemodule_elements();

$this->add_action_buttons();
}
}
</code>

The above example does not contain the full file, just enough to provide you with an idea. First we create a text element called 'name' that is required, this is obviously the name of the instance. I then created another element that stores whether a user wishes to display the unique code issued to a user when they receive the certificate or not with a default value of 0 and a help button explaining what this setting does. The function standard_coursemodule_elements adds the elements common to all modules, such as the conditional fields. The add_action_buttons function adds the submit and cancel buttons to the form. This data will be passed to either <modname>_add_instance or <modname>_update_instance depending on whether you are adding a new instance or updating a current one. You can also add validation to this form, just like any other form in Moodle. For more information on how to create forms in Moodle see [[Form_API]].

=== index.php ===

This page is used by Moodle when listing all the instances of your module that are in a particular course with the course id being passed to this script. The beginning of the page should contain the following -

<code php>
require_once('../../config.php');

$id = required_param('id', PARAM_INT); // Course ID

// Ensure that the course specified is valid
if (!$course = $DB->get_record('course', array('id'=> $id))) {
print_error('Course ID is incorrect');
}
</code>

You are then free to display the list of instances as you wish.

=== view.php ===

When a course renders its page layout and activities it generates the links to view them using the view.php script, so the links will look like <wwwrootofyoursite>/mod/<modname>/view.php?id=4, where 4 is the course module id. For the certificate example the beginning of the view.php page looks like the following -

<code php>
require_once('../../config.php');
require_once('lib.php');

$id = required_param('id', PARAM_INT); // Course Module ID

if (!$cm = get_coursemodule_from_id('certificate', $id)) {
print_error('Course Module ID was incorrect');
}
if (!$course = $DB->get_record('course', array('id'=> $cm->course))) {
print_error('course is misconfigured');
}
if (!$certificate = $DB->get_record('certificate', array('id'=> $cm->instance))) {
print_error('course module is incorrect');
}
</code>

The course module id is passed to this script and set as $id, which is then used to retrieve the course data and the information from the certificate table which we can use later on as we wish.

=== version.php ===

The version.php file keeps track of the version of your module, and other attributes, such as what version of Moodle it requires. For a full list of the attributes please see [[version.php]].

Git repositories for contrib modules

2012-11-06T01:38:17Z

Nicolasconnault: /* Moving a plugin to it's own repository */

{{draft}}

The instructions here assume that you have a working knowledge of git.

Managing contrib plugin with git makes it easy to make local modifications and pull in updates.
There are several options for managing a contrib plugin with git:
# Add the module to your main moodle git repository
# Create a self-contained repository for the plugin in a subdirectory
# Create a git submodule, which creates a repository for the plugin but tracks updates in the main repository too. It also allows you to clone the plugins with the main repository
Having used all of the above, the method I'd recommend is number 2, as it's most convenient. The main disadvantage of 1 is that you can't easily pull in updates, and the main disadvantage of 3 is that you have to make each commit to the module twice (once in the submodule, and once in the main repo).

== Creating a new plugin ==
If you intend to publish the plugin, I highly recommend creating a [http://github.org github] repository from the start. This will allow you to publish with a single command when you're ready. Just go to the site, sign up for an account, create a new repository. The naming convention for Moodle plugin repositories is <tt>moodle-plugintype_pluginname</tt>.

Github will give you instructions for cloning your (blank) repository. If you're using option 2 above, navigate to the directory for the plugin type you're developing (e.g. /block, /mod, /local) and run the <tt>git clone</tt> command there. This will create a subdirectory called <tt>moodle-plugintype_pluginname</tt>, rename this to <tt>pluginname</tt> and you're good to go. <tt>cd</tt> into this directory to perform git commands on this plugin's repository - outside of this directory will perform them on the main Moodle repository.

You can then develop and test your changes locally, and when you're ready to publish, run
git push origin

== Installing a third-party plugin ==
Installing a plugin developed by a third party differs depending on whether they have used git or not.
If they have used git, you can follow the instructions above, but skip out the part where you create a new github repository and clone their own github (or other public repository) instead.

If they haven't used git, you can still use git (and even github, if you like) to track local modifications to the plugin. Simply create a directory for the plugin
mkdir ~/moodle/blocks/newblock
Initialise a new git repository there
cd ~/moodle/blocks/newblock
git init
unzip or copy the files to the repository
cd ~
tar -xf newblock.tar.gz
cp newblock/* ~/moodle/blocks/newblock
add and commit the files
cd ~/moodle/blocks/newblock
git add .
git commit . -m "Added files for newblock"
When installing updates, you'll need to copy the new files in place of the old one, and re run the <tt>git add</tt> and <tt>git commit</tt> commands.

== Moving a plugin to its own repository ==
You may have developed a plugin within your main Moodle repository, but want to move it to a separate one to make it easier to publish. Using <tt>git filter-branch</tt>, we can achieve this and maintain all existing history for the plugin's files.

First, you'll need a fresh copy of moodle (this will become your new moodle repository)
mkdir ~/newmoodle
cd ~/newmoodle
git clone git://git.moodle.org/moodle.git
This will create a clone of Moodle without your plugins in ~/newmoodle/moodle
Next, you need to clone your local Moodle repository (why will become clear).
mkdir ~/moodleclone
cd ~/moodleclone
git clone ~/moodle
This will create a clone of your current moodle development repository, with your plugins, in ~/moodleclone/moodle
Now, we'll use the <tt>git filter-branch</tt> command to reduce this clone to just the plugin.
cd ~/moodleclone/moodle
git filter-branch --subdirectory-filter blocks/myblock/
The files from blocks/myblock/ will now be at the root of the repository. All other files will have been removed (this is why we're using a clone).
You can now track the plugin in it's own repository by cloning this reduced repository to a subdirectory of the new moodle clone.
cd ~/newmoodle/blocks
git clone ~/moodleclone/moodle myblock
This will clone the block's files, with the full history, into their own repository in the myblock subdirectory.
You can now delete ~/moodleclone/moodle, and repeat with any other plugins you've developed.

== See also ==

* [[:en:Git|Git]]
* [[Git tips]]
* [[User:Sam Hemelryk/My Moodle Git workflow]]

; Moodle forum discussions
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]
* [http://moodle.org/mod/forum/discuss.php?d=167063 Handy Git tip for tracking 3rd-party modules and plugins]
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]

; External resources
* [http://www.kernel.org/pub/software/scm/git/docs/everyday.html Everyday GIT With 20 Commands Or So]
* [http://gitref.org/ Git Reference]
* [http://progit.org/book/ Pro Git book]

[[Category:Git]]

Page API

2012-11-05T12:09:41Z

Nicolasconnault: /* URL */

The Page API is used to set up the current page, add JavaScript, and configure how things will be displayed to the user.

==Overview==
The Page API is an integral part of any Moodle page. It allows the developer to set things up the way they envisage it. Through the Page API you can set things like the title, initial heading, where the user is for the navigation, and which layout you think the page should use.

This document starts off with a simple example, and then proceeds to provide a more complete description of how to set up a page for display.

==A simple example==
This example covers how to set up a basic page for use within an activity plugin and is undoubtedly the simplest example as much of the work is done behind the scenes for you.
<code php>
// File: /mod/mymodulename/view.php
require_once('../../config.php');
$cmid = required_param('id', PARAM_INT);
$cm = get_coursemodule_from_id('mymodulename', $cmid, 0, false, MUST_EXIST);
$course = $DB->get_record('course', array('id' => $cm->course), '*', MUST_EXIST);

require_login($course, true, $cm);
$PAGE->set_url('/mod/mymodulename/view.php', array('id' => $cm->id));
$PAGE->set_title('My modules page title');
$PAGE->set_heading('My modules page heading');

// The rest of your code goes below this.
</code>
I'm going to assume you know what the first four lines are doing, if not you are starting in the wrong place.

So lets start at require_login and assume you already have the course and course module objects ready to use. When you call require_login part of the magic it does for you is set up the basic for the current page. 
In the case of the example above because require_login is given a course and course module it is already setting up much of the page for you. It is giving the course and course module objects to the page, setting the context for the page to the course modules context, and setting the page layout to ''incourse'' so that you get the standard look of a course module.

The set up that we are having to do is as follows:
# Set the URL for the page. This MUST be done.
# Set a title for the page. Most likely will be shown in the <title> tag.
# Set the heading for the page. Most likely used in the pages header.

It's important to mention that this has to be done before output starts. That means you must set up the page before the header is printed and before you instantiate any moodleform instances.

And that is it, if you were to add a bit of simple output there you would get a page that already looks like other module pages you would have seen. Simple as.

==$PAGE The Moodle page global==
For every page request Moodle sets up a couple of global structures that you will likely need. $DB the database object, and $CFG which stores configuration are two that you are likely already aware of. $PAGE is the focus of this article, it is a moodle_page instance that stores all of the information and is used by the output library $OUTPUT when displaying the page. 
It's important to note the difference between $PAGE and $OUTPUT, $PAGE is for setting up the page and $OUTPUT is for displaying the page. $PAGE contains lots of logic and magic, $OUTPUT is purely about display and does little more than produce HTML.

==Setting up the page==
When creating a page in Moodle there are a couple of things that you must set, and a couple of things that get set for you in many cases but not all of the time.

===URL===
This is an absolute must, failing to set this will lead Moodle to display an error that it has not been set. 
It can be set in the following manner:

<code php>
$PAGE->set_url(new moodle_url('/page/to/your/file.php', array('key' => 'value', 'id' => 3)));
$PAGE->set_url('/page/to/your/file.php', array('key' => 'value', 'id' => 3));
$PAGE->set_url('/page/to/your/file.php?key=value&id=3');
</code>

The above code sets the page URL 3 times, and highlights the 3 different ways you can set the URL. Either of the first two methods are the preferred way as it provides 100% accuracy when processing the URL. Internally set_url() converts what ever you give it to a moodle_url object.

The URL that you give to the page is going to be used by many Moodle core API's. Most importantly it is going to be used to create the navigation for your page so it's very important you set it accurately.

===Context===
This is an absolute must as well, however in many cases it will be set for you magically by Moodle.

In order to set the context for the page you must provide a context object, in Moodle 2.2 and greater this will look as follows:
<code php>
// Moodle 2.2 and greater
$PAGE->set_context(context_system::instance());
$PAGE->set_context(context_coursecat::instance($categoryid));
$PAGE->set_context(context_course::instance($courseid));
$PAGE->set_context(context_module::instance($moduleid));
</code>

In Moodle 2.0+, and Moodle 2.1+ the following is the equivalent code:
<code php>
// Moodle 2.2 and greater
$PAGE->set_context(get_system_context());
$PAGE->set_context(get_context_instance(CONTEXT_COURSECAT, $categoryid));
$PAGE->set_context(get_context_instance(CONTEXT_COURSE, $courseid));
$PAGE->set_context(get_context_instance(CONTEXT_MODULE, $moduleid));
</code>

In both examples above setting different types of contexts has been illustrated however you should only ever call set_context() once with the context that is most appropriate to the page you are creating. 
If it is a plugin then the context to use would be the context you are using for your capability checks.

As mentioned above the other thing to be aware of is that in some circumstances this gets automatically set for you. 
If your script calls require_login (and most scripts have to) and you are providing a course, or a module to your require login call then you will not need to call set_context(). 
This is because require_login handles it for you.

If your script doesn't call require_login, or you don't call it with a course and/or module then you will need to manually set the context as shown.

===Optional set up===
The following are optional extras you can set up against the PAGE object that you are likely to encounter throughout Moodle core, and are likely to want to use yourself.
====Page layout====
The following code sets the pages layout to the standard layout, the most generic layout in the arsenal.
<code php>
$PAGE->set_pagelayout('standard');
</code>
When setting the page layout you should use the layout that is the closest match to the page you are creating. Layouts are used by themes to determine what is is shown on the page. The most prominent difference between layouts is the block regions they support. The default layout `''base''` for example doesn't normally have any block regions at all, where as normally `''standard''` has the most generic layout and several block regions.

There are dozens of different layouts that can be, and are used throughout Moodle core that you can use within your code. For a full list of common layouts you are best too look at theme/base/config.php or refer to the list below.

Note: It's important to know that the theme determines what layouts are available and how each looks. If you select a layout that the theme doesn't support then it will revert to the default layout while using that theme. Themes are also able to specify additional layouts, however its important to spot them and know that while they may work with one theme they are unlikely to work as you expect with other themes.

====Base theme page layouts====
The following is a list of the layouts defined by the base theme. Theme designers are encouraged to make the base theme a parent of their custom theme so you can be sure that in 99% of cases these layouts will be available.
{| class="nicetable"
|-
! Layout
! Description
|-
| base
| Most backwards compatible layout without the blocks. This is the layout used by default.
|-
| standard
| Standard layout with blocks, this is recommended for most pages with general information
|-
| course
| The course main page uses this layout.
|-
| coursecategory
| Category course listings.
|-
| incourse
| Used for areas within a course, typical for modules. Default page layout if $cm specified in require_login().
|-
| frontpage
| The site home page uses this.
|-
| admin
| Admin and settings pages as well as server administration scripts.
|-
| mydashboard
| The users dashboard.
|-
| mypublic
| A users public profile uses this layout.
|-
| login
| The login screen.
|-
| popup
| Pages that appear in popup windows, usually no navigation, blocks, or header.
|-
| frametop
| Used for the outermost content of a page constructed with frames. Usually no blocks and minimal footer.
|-
| embedded
| Embedded pages such as content for iframes/objects. Needs as much space as possible usually no blocks, header, or footer.
|-
| maintenance
| Used during upgrade, installation, and when maintenance mode is enabled.
|-
| print
| Gets used when printing a page. Normally just a simple header and no blocks.
|-
| redirect
| A special layout used during a redirect. Normally with content only.
|-
| report
| Used for reports within Moodle. Special layout designed to handle horizontal scrolling in a nice way.
|}

====Title====
Setting an appropriate title is certainly a must for any properly designed page. While it is optional it is highly recommended that you set the title.
<code php>
$PAGE->set_title('This is my title');
</code>
When setting the title for the page you need to provide just the string you want to use for the title. It should be a basic string and contain no HTML. Any HTML will be stripped out as the title is used within the <title> tag in the HTML head.

====Heading====
Like title it is highly recommended that you set a meaningful heading for the page, although it is optional. The heading is normally displayed at the top of the page before the rest of the content starts. However it is up to the layout defined by the theme as to where it is displayed. Not all layouts will display a heading but I encourage you to always set one even if you are using a layout that doesn't support headings. This way if you are using a theme that uses a heading on every page regardless of layout things still look consistent.

<code php>
$PAGE->set_heading(get_string('pluginname', 'local_myplugin'), 3);
</code>

When setting a heading there is just one argument, the string to use for the heading. It should be a basic string and contain no HTML.

=== Advanced set up ===
The following are advanced optional methods you can call to further set up your page. In most cases you will never need to use these.

; set_activity_record : If you have called require_login with a course module, or you have manually set a course module on $PAGE then one other thing you may want to do is set the activity module record on $PAGE as well. This is best done when you have already fetched the activity record yourself in which case manually setting the activity record may reduce the number of queries for the page by 1.
<code php>$PAGE->set_activity_record($activityrecord)</code>

; set_blocks_editing_capability : Using this method you can set an additional capability that users must posses before being able to edit blocks on this page. By default 'moodle/site:manageblocks' is used however there are sometimes reasons to use a different capability.
<code php>$PAGE->set_blocks_editing_capability($strcapability)</code>

; set_button : This allows you to set some HTML that will be shown in the navigation bar where the `Turn on editing` button normally lives.
<code php>$PAGE->set_button($htmlstring)</code>

; set_cacheable : By setting this to false the page will be sent with headers to prevent the client from caching the page. Defaults to true.
<code php>$PAGE->set_cacheable(true/false)</code>

; set_category_by_id : Allows you to set a category that this page is displaying. Calling this will force the $PAGE->course to be set to the front page course.
<code php>$PAGE->set_category_by_id($categoryid)</code>

; set_cm : Like set page above, sometimes you need to manually set the course module for $PAGE. Again you must set the context to the context of the course module if you call this.
<code php>$PAGE->set_cm($coursemodulerecord)</code>

; set_course : This allows you to set the course the page belongs to. Normally when you call require_login the course you give it automatically gets sent to $PAGE for you. However if you don't want to require login for the course, but you need it in $PAGE then you can call set_course and provide it. Note that if you do this then you MUST use the context of the course when calling set_context().
<code php>$PAGE->set_course($courserecord)</code>

; set_docs_path : Normally this gets automatically constructed for you, however in some circumstances you may want to manually set it. This allows you to have several pages that all point to the same docs page rather than requiring a docs page for each. The docs page link is normally shown by a theme in the footer.
<code php>$PAGE->set_docs_path($strpath)</code>

; set_focuscontrol : If you pass this method an element id when the page loads on the client focus will be shifted to the element with the corresponding id. Using this function is a REALLY bad idea in most situations because changing focus automatically in a browser is a nightmare for the vision impaired and those using screen readers.
<code php>$PAGE->set_focuscontrol($controlid)</code>

; set_headingmenu : This allows you to set some HTML that will be shown next to the pages main heading where the language select box normally lives.
<code php>$PAGE->set_headingmenu($htmlstring)</code>

; set_other_editing_capability : Can be used to set an additional capability that the user must posses before they can turn editing on for this page. This is useful if you can an editing more for your page that is more than just editing blocks.
<code php>$PAGE->set_other_editing_capability($strcapability)</code>

; set_pagetype : This gets automatically set up for by default to the path of your file e.g. mod/mymod/index.php will set up as mod-mymod-index. This is absolutely fine in 99% of cases however every now and again there is a reason to override it.
<code php>$PAGE->set_pagetype($strpagetype)</code>

; set_periodic_refresh_delay : If set a meta tag gets added to the page header causing it to refresh intermittently. This is rarely needed but can be useful if you need to automatically refresh the likes of a chat page, or news feed. Today it is not recommended to use this, but instead to create a means of getting additional content via AJAX.
<code php>$PAGE->set_periodic_refresh_delay($intdelay)</code>

; set_popup_notification_allowed : Allow or disallow popup notifications on this page. Things like messaging can cause messages to popup at the bottom of the screen sometimes. On some pages this functionality is not desired and can be stopped by calling this method and using false as the first argument. Popups are allowed by default.
<code php>$PAGE->set_popup_notification_allowed(true/false)</code>

; set_subpage : If context->id and pagetype are not enough to uniquely identify this page and you need to include another string to make it more unique you can do it by calling this method setting a custom sub page type.
<code php>$PAGE->set_subpage($strsubpage)</code>

; add_body_class : Adds a CSS class to the body tag that will be printed by the Output API as part of the header. This is useful for adding classes to the body tag that describe the content of the page and may be required for styling the whole page, or for including indicator classes that may be useful to look for in JavaScript.
<code php>$PAGE->add_body_class($strcssclass)</code>

; add_body_classes : Adds an array of CSS classes to the body tag. Have a look at the above comment for '''add_body_class''' for more details.
<code php>$PAGE->add_body_classes($arrayofclasses)</code>

==Getting information about the page==
As well of setting up the page you can of course get information back from it about the page it has been set up to display. 
Anything you set against the page can be retrieved as can any information that was set magically for you by other methods.

The following are the most interesting and likely useful things you can get back from the page.

; activityrecord : The activityrecord will be the record from the database that relates to the cm that was set by require_login, or manually by your code. For example if you provided a $cm instance that related to a forum this will be a row from the forum table.
<code php>$var = $PAGE->activityrecord;</code>

; blockmanager : This is the block manager responsible for loading the all of the blocks that will be shown on the page. For more information see the [[Blocks API]].
<code php>$var = $PAGE->blockmanager;</code>

; bodyid : The id that will be given to the body tag when the page is displayed.
<code php>$var = $PAGE->bodyid</code>

; categories : An array of all the categories the page course belongs to, starting with the immediately containing category.
<code php>$var = $PAGE->categories</code>

; category : The category that the page course belongs to.
<code php>$var = $PAGE->category</code>

; cm : The course module that has been set for the page.
<code php>$var = $PAGE->cm</code>

; course : The course that has been set for the page.
<code php>$var = $PAGE->course</code>

; devicetypeinuse : The device the user is using browse the page.
<code php>$var = $PAGE->devicetypeinuse</code>

; headerprinted : Is true if the page header has already been printed.
<code php>$var = $PAGE->headerprinted</code>

; heading : The page heading.
<code php>$var = $PAGE->heading</code>

; navbar : Gets a reference to the pages navigation bar so that you can interact with that. See the [[Navigation API]] for more information.
<code php>$var = $PAGE->navbar</code>

; navigation : Gets a reference to the navigation for the page. See the [[Navigation API]] for more information.
<code php>$var = $PAGE-></code>

; requires : Gets the page requirements manager that handles any JavaScript and special CSS requirements for the page.
<code php>$var = $PAGE->requires</code>

; settingsnav : Gets the settings navigation for the page. See the [[Navigation API]] for more information.
<code php>$var = $PAGE->settingsnav</code>

; theme : Gets the theme that is being used for the page. Is a theme_config object.
<code php>$var = $PAGE->theme</code>

; title : Gets the title for the page.
<code php>$var = $PAGE->title</code>

; url : Gets the URL that was set for the page. Is a moodle_url object.
<code php>$var = $PAGE->url</code>

==FAQs==

; I don't have any blocks on my page? : This has happened because you have not set a page layout that uses blocks OR you have set it after output has started. Once output has started you cannot change integral aspects of that page that are used for the initial output. Included is the page title, heading, url and layout.

; I am getting a notice about not having set the page URL but I have set it? : As above you must set up the page before output starts, trying to do so will lead to notices and developer warnings about having things in the wrong order.

; What starts output? : Output starts when either the script calls echo $OUTPUT->header OR a moodleform is instantiated.

==Related API's==
There are a couple of API's that are closely related to the Page API that you should be aware of as well.

===Output API===
The output API is an immediate relation of the page API. The page API is about setting things up, whereas the output API is all about displaying things.
It's through the output API that content is actually produced, and much of the information you set up through the page is used to customise what is produced, and fill in the general blanks of any page (such as title and heading.

See the [[Output API]] documentation for more information.

===Page requirements API===
The page requirements API allows you the developer to include additional CSS, and JavaScript resources that should be included with the page, and to include JavaScript calls within the page through a variety of means.
Technically this API is part of the Output API mentioned above, however it deserves special mention. If you are going to be using any JavaScript or CSS within your page you will need to know about this.

See the [[Output API]] documentation for more information on the page requirements API.

===Navigation API===
The final API to mention is the navigation API. This again is integral to both the page and output API and is used to recognise the context of the content being displayed and ensure that the correct blocks and navigaiton structure are loaded for the context.
There is a good chance that you will encounter a need to customise the navigation early on in plugin page development and it's important to be aware of this important API.

See the [[Navigation API]] documentation for more information on the page requirements API.

==See also==

* [[Core APIs]] : A list of all the core API's in Moodle.
* [[Output API]] : The Output API.
* [[Navigation API]] : The Navigation API.
* [http://moodle.org/mod/forum/view.php?id=55 General developer forum] : The place to ask question you may have about the Page API.
* MDL-30977 : The issue to see the Page API properly documented.

[[Category:API]]

Navigation API

2012-11-05T06:06:32Z

Nicolasconnault: incorrect use of apostrophes

==Overview==
The Navigation API allows for the manipulation of the navigation system used in Moodle.

==What the navigation is==
It's very important to understand what the navigation is exactly within Moodle. One of the goals for Moodle 2.0 was to standardise navigation throughout Moodle and try to bring order to the structure of a Moodle site. Navigation is available through the page object '''$PAGE''', against which you set the heading for the page, the title, any JavaScript requirements, etc. The navigation structure uses the information $PAGE contains to generate a navigation structure for the site. The navigation or settings [[blocks]] are interpretations of the navigation structure Moodle creates.

This navigation structure is available through three variables:

; $PAGE->navigation : This is the main navigation structure, it will contain items that will allow the user to browse to the other available pages.
; $PAGE->settingsnav : This is the settings navigation structure contains items that will allow the user to edit settings.
; $PAGE->navbar : The navbar is a special structure for page breadcrumbs.

==What the navigation is not==
The navigation is '''NOT''' the navigation block or the settings block! These two blocks were created to display the navigation structure. The navigation block looks at ''$PAGE->navigation'', and the settings block looks at ''$PAGE->settingsnav''. Both blocks interpret their data into an HTML structure and render it.

# The navigation is a back-end structure that is built behind the scenes and has no immediate method of display.
# The navigation and settings blocks display the back-end navigation structure but add nothing to it at all.
::In the [[model-view-controller pattern]], $PAGE->navigation, $PAGE->settingsnav, and $PAGE->navbar are the models, and the blocks are views.

The navbar is just the path to the active navigation or settings item. The navbar is not displayed by a block; instead it is added into the theme's layout files and displayed by the core renderer.

==How the navigation works==

The main navigation structure can be accessed through '''$PAGE->navigation'''. The navigation and settings are contextual in that they will relate to the page that the user is viewing. This is determined by other $PAGE object properties:
* '''$PAGE->context''' is a Moodle context that immediately outlines the nature of the page the user is viewing.
* '''$PAGE->course''' is the course the user is viewing. This is essential if the context is CONTEXT_COURSE or greater. However, it is also useful in other contexts such as CONTEXT_USER.
* '''$PAGE->cm''' is the course module instance. This is essential if the context is CONTEXT_MODULE or greater.
* '''$PAGE->url''' is used to match the active navigation item.

Nearly every page sets $PAGE->url through a call to '''$PAGE->set_url''' however not many explicitly set the context, course, or cm. When you call '''require_login''' with a course or cm it automatically calls the following:
<code php>
if ($cm) {
$PAGE->set_cm($cm, $course); // sets up global $COURSE
} else {
$PAGE->set_course($course);// sets up global $COURSE
</code>

A page will only be required to explicitly set a context, course, or cm under one of these conditions:
# '''require_login''' is NOT being called correctly
# The page is using CONTEXT_SYSTEM, CONTEXT_COURSECAT, or CONTEXT_USER (call '''$PAGE->set_context''' ).
# The page is using a course or cm but it is also using one of the above contexts (call '''$PAGE->set_course''' or '''$PAGE->set_cm''' ).

The navigation structure cannot be generated before the $PAGE object is configured. It is only generated when it is first used, either when something tries to access the structure or when code tries to add to it. The navigation is initialised in a specific order:
# Main navigation structure
# Settings navigation
# Navbar (does not need to be generated because of its simple contents and rendering)

==Extending the navigation==

===Code extension===
This method of extending is when the code arbitrarily extends the navigation during its execution. Extending the navigation through this means allows you to extend the navigation anywhere easily, however it will only be shown on pages where your extending code gets called (you should probably put it in a function within lib.php).

These examples are taken from the [http://moodle.org/mod/forum/discuss.php?d=152391 General Developer Forum: Moodle 2 - how to set up breadcrumbs for a module page]. It has further information that is well worth reading.
====Navigation====
This is extending the main navigation structure.
<code php>
$previewnode = $PAGE->navigation->add(get_string('preview'), new moodle_url('/a/link/if/you/want/one.php'), navigation_node::TYPE_CONTAINER);
$thingnode = $previewnode->add(get_string('name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>
The above lines of code adds a preview node to the bottom of the navigation and then adds a thingnode to the previewnode (adding a leaf to our tree).
The final line of code makes the thingnode active so that the navbar finds it however if the URL you give it is the same as the url you set for the page it will automatically be marked active and you won't need this call.

Next extending the navigation for the course.
For this you will need to know the course id and have called require_login($courseorid); so that the navigation is loaded for the course.
<code php>
$coursenode = $PAGE->navigation->find($courseid, navigation_node::TYPE_COURSE);
$thingnode = $coursenode->add(get_string('Name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>
The new bit of code here really is the first line which simply finds the course node, to do this we give it the course id and the node type in this case TYPE_COURSE.
What we are doing here is relying on the navigation to generate the navigation up to the course and then just adding to the course.
====Settings navigation====
Adding to the settings navigation is very similar to navigation
<code php>
$settingnode = $PAGE->settingsnav->add(get_string('setting'), new moodle_url('/a/link/if/you/want/one.php'), navigation_node::TYPE_CONTAINER);
$thingnode = $settingnode->add(get_string('Name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
$thingnode->make_active();
</code>
====Navbar====
This is extending the settings navigation.
<code php>
$PAGE->navbar->ignore_active();
$PAGE->navbar->add(get_string('preview'), new moodle_url('/a/link/if/you/want/one.php'));
$PAGE->navbar->add(get_string('name of thing'), new moodle_url('/a/link/if/you/want/one.php'));
</code>
The above code tells the navbar to ignore what ever the active page was and just use what you add, at which point we add two items as shown.
===Plugin Callbacks===
These are specific functions that the navigation looks for and calls if they exist for the plugin, presently only three plugin types can extend the navigation through these call-backs.
====Module====
Modules have two call-back methods, first to extend the navigation, and second to extend the settings. These call-backs get called when ever the user is viewing a page within the module and should only extend the navigation for the module.
<code php>
function {modulename}_extend_navigation(${modulename}node, $course, $module, $cm)
function {modulename}_extend_settings_navigation($settings, ${modulename}node)
</code>

====Course Formats====
Course formats are able to completely redefine the way in which navigation is generated for a course, as well as this they also have several methods to ensure the navigation is generated correctly.
====Course Reports====
By default reports don't add themselves or anything else to the navigation however there is a call-back that can be implemented to allow them to do so.

==FAQ's and troubleshooting==
'''Q.''' My page is on the navigation but it doesn't find it?

The first thing to do here is check the URL you are setting for the page. It should match the URL your page has within the navigation. If it doesn't you have two options, first change your '''$PAGE->set_url''' call, or second override the URL the navigation is using to find the active node as shown below:
<code php>
navigation_node::override_active_url(new moodle_url('/your/url/here.php', array('param'=>'value')));
</code>

==See also==

* [[Core APIs]]

[[Category:API]]

Moodle architecture

2012-11-05T05:44:19Z

Nicolasconnault: Minor typo

The aim of this document is to quickly give an overview of how the Moodle works at a technical level. Hopefully this will be helpful to Administrators and Developers. However, to actually do Moodle development you will have to study the code in much more detail than is provided here. See the [[Developer_documentation|developer documentation]].

==What is Moodle?==

Moodle is a Learning Management System, Course Management System, or Virtual Learning Environment, depending on which term you prefer. Its goal is to give teachers and students the tools they need to teach and learn. Moodle comes from a background of [[:en:Pedagogy|Social Constructionist pedagogy]], however, it can be used to support any style of teaching and learning.

There are other types of software systems that are important for educational institutions, for example ePortfolios, Student Information Systems and Content repositories. Generally, Moodle does not try to re-invent these areas of functionality. Instead, tries to be the best LMS possible, and then interoperate gracefully with other systems that provide the other areas of functionality. It is, however, perfectly possible to use Moodle as a stand-alone system, without integrating it with anything else.

Moodle is a web application written in PHP. Moodle is open source. Copyright is owned by individual contributors, not assigned to a single entity, although the company Moodle Pty Ltd in Perth Australia, owned by Moodle's founder Martin Dougiamas, manages the project.

==Overview of a Moodle installation==

A Moodle installation comprises the Moodle code executing in a PHP-capable web server; a database managed by MySQL, PostgreSQL, Microsoft SQL Server, or Oracle; and a file store for uploaded and generated files (the moodledata folder).

All three parts can run on a single server; or they can be separated with many load-balanced web-servers, a database cluster, and a file-server; or anywhere between those extremes.

Moodle is designed to be simple to install on any server that meets these basic requirements. Moodle self-installs once the code has been copied to the web server and a blank database created (see [[:en:Installing Moodle]]). Similarly, Moodle can always self-upgrade from one version to the next (see [[:en:Upgrading]]).

==Moodle as a modular system==

Like many successful open source systems, Moodle is structured as an application core, surrounded by numerous plugins to provide specific functionality. Moodle is designed to be highly extensible and customizable without modifying the core libraries, as doing so would create problems when upgrading Moodle to a newer version. So when customizing or extending your own Moodle install, always do so through the plugin architecture.

Plugins in Moodle are of specific types. That is, an authentication plugin and an activity module will communicate with Moodle core using different APIs, tailored to the type of functionality the plugin provides. Functionality common to all plugins (installation, upgrade, permissions, configuration, ...) are, however, handled consistently across all plugin types.

The standard Moodle distribution includes Moodle core and a number of plugins of each type, so that a new Moodle installation can immediately be used to start teaching and learning. After installation a Moodle site can be adapted for a particular purpose by changing the default configuration option, and by installing and removing plugins. Most plugins that have been shared publicly are listed in the [http://moodle.org/plugins/index.php Moodle Plugins Directory].

Physically, a Moodle plugin is just a folder of PHP scripts (and CSS, JavaScript, etc. if necessary). Moodle core communicates with the plugin by looking for particular entry points, often defined in the file <tt>lib.php</tt> within the plugin.

==An overview of Moodle core==

''Apologies, this section is not complete yet. If you have the knowledge and time, please add to it.--[[User:Tim Hunt|Tim Hunt]] 18:28, 8 December 2010 (UTC)''

Moodle core provides all the infrastructure necessary to build an LMS. It implements the key concepts that all the different plugins will need to work with. These include

===Courses and activities===

A Moodle course is a sequence of activities and resources grouped into sections. Courses themselves are organised into a hierarchical set of categories within a Moodle site.

===Users===

Users, profile, my moodle ...

===Groups and cohorts===

===Enrolments and access control===

Contexts, roles, capabilities, and permissions, ...

===Activity and course completion===

===Navigation, settings and configuration===

===Forms library===

===JavaScript library===

Moodle has adopted the [http://developer.yahoo.com/yui/3/ Yahoo User Interface library]. There is also a nice system for loading the additional JavaScript files required by each page.

===Installation and upgrade===

===Logs and statistics===

==The most important plugin types==

===Activities and resources===

Activities and resources are the most basic individual components that make up a course and are the main tools for teaching and learning. Some examples of resources are: pages, links and IMS content packages. Examples of activities include: forums, wikis, quizzes, and assignments.

Activities are by far the largest type of plugin in terms of amount of code. A forum or wiki system could be a software project in its own right. Both activities and resources are installed in the <tt>mod</tt> folder.

===Blocks===

Blocks are small bits of interface functionality that can be added to (normally the sides of) pages. Many blocks provide additional views of data stored and modified elsewhere. Blocks live in the <tt>blocks</tt> folder.

===Themes===

The overall visual style of a Moodle site, a particular course, or all courses in a category, can be changed by selecting a different theme at these different levels. Themes are the standard way of making aesthetic changes to your Moodle application, decoupling presentation from content and functionality.

Themes live in the <tt>theme</tt> folder, and published themes are listed in the [http://moodle.org/mod/data/view.php?id=6552 Themes database].

===Language packs===

Moodle is internationalised. That is, you can get language packs for many different languages. Language packs are normally downloaded and installed via the Moodle administration screens, but they can also be downloaded manually from [http://download.moodle.org/langpack/ Moodle.org: language packs].

Administrators can also manually change any of the standard user interface strings if the terms used in the installed language pack are not appropriate.

===Course formats===

control how the structure of the course, a sequence of activities grouped into sections, is presented to the users. Course formats live in the <tt>course/format</tt> folder.

===Authentication plugins===

control how users log in. Moodle can manage usernames and passwords itself, or use those stored in LDAP or another database. Alternatively, Moodle can use a number of single-sign-on schemes. Authentication plugins live in the <tt>auth</tt> folder.

===Enrolment plugins===

control which users are enrolled in which courses. Again this can be by synchronising with another system, perhaps a student information system, or it can be tracked internally by Moodle. Enrolment plugins live in the <tt>enrol</tt> folder. (Moodle was created by an Australian, so enrol is the correct spelling ;-).)

===Repository plugins===

Ways for users to get content (files) into Moodle, either by uploading from their hard drive, or by getting the file from another location on the Internet, perhaps Drop Box, Google Docs, or Flickr. Repository plugins live in the <tt>repository</tt> folder.

===Others===

There are [[Developer_documentation#Make_a_new_plugin|many more types of plugins]] (more than 30 at the last count). These include text filters, question types, gradebook reports, admin reports, course reports, plagiarism detection services and web service protocols.

For a definitive, up-to-date list, look at the value returned by the <tt>get_plugin_types()</tt> function, which is defined in <tt>lib/moodlelib.php</tt>.

==How Moodle code is organised==

Moodle mostly follows a [http://martinfowler.com/eaaCatalog/transactionScript.html transaction script] approach. That is, suppose you are looking a Forum. The URL will be <tt>.../mod/forum/view.php?id=1234</tt>. and <tt>mod/forum/view.php</tt> the PHP script that generates that page. One could argue that transaction script is not an appropriate pattern for an application as complex as Moodle. However, it is a very natural architecture for a PHP application, and Moodle is an aggregate of many different plugins, rather than a single complex application.

Behind that basic transaction script approach, a lot of the core functionality has be refactored out into libraries (mostly in the <tt>lib</tt> folder). This provides elements of a [http://martinfowler.com/eaaCatalog/domainModel.html domain model]. The Moodle project started before PHP could handle object-oriented code, however, so don't expect an object-oriented domain model except in some of the more recent parts of the Moodle code.

There are two layers used to separate presentation from the business logic. The outer layer is the theme (see above) which controls the more visual aspects of the Moodle interface. Then there are renderer classes which generate the HTML to be output from the data supplied by the transaction scripts and the domain model. Unfortunately, neither PHP, nor the Moodle architecture, enforces a clear separation of the UI layer. It is possible for sloppy developers to make a mess, and this has happened in the past. The code in the standard Moodle distribution is gradually being cleaned up.

==The Moodle database==

The Moodle database comprises many tables (more than 250) because the whole database is an aggregate of the core tables and the tables belonging to each plugin. Fortunately, this large structure is understandable, because the tables for one particular plugin typically only link to each other and a few core tables. See [[Database_schema_introduction|Database schema introduction]] for more information.

The Moodle database structure is defined in <tt>install.xml</tt> files inside the <tt>db</tt> folder in each plugin. For example <tt>mod/forum/db/install.xml</tt> contains the database definition for the forum module. <tt>lib/db/install.xml</tt> defines the tables used by Moodle core. The <tt>install.xml</tt> files contain comments that should explain the purpose of each table and column. These comments can be turned into human-readable documentation by going to Site administration -> Development -> XMLDB editor in your Moodle installation, and clicking on the [Doc] link.

==See also==

* [[:en:Administrator documentation]]
* [[Developer_documentation|Developer documentation]]
* [[Database_schema_introduction|Database schema introduction]]
* [http://moodle.org/mod/data/view.php?id=6009 Modules and plugins] and [http://moodle.org/mod/data/view.php?id=6552 themes] databases
* [http://moodle.org/mod/forum/discuss.php?d=64465 Forum thread with a vigorous argument about whether an architecture document is a good idea, which eventually lead to this page being rewritten]
* [http://www.aosabook.org/en/moodle.html The chapter of The Architecture of Open Source Applications about Moodle]

[[Category:Coding guidelines]]

User:Nicolas Connault

2010-07-11T11:21:46Z

Nicolasconnault: Removing all content from page

User:Nicolas Connault

2009-10-26T22:31:42Z

Nicolasconnault: /* Contact Details */

==Contact Details==
ICQ: 826611
Yahoo : nicolasconnault
AIM: NikoZeta
Skype: nicolasconnault
Email: nicolasconnault@gmail.com
Cell: 0435423748

==First steps towards Moodle==
Born in 1978 in France, I have 4 brothers and 1 sister. At age 19, I spent 2 years on a mission in England for the [http://www.mormon.org Church of Jesus Christ of Latter-Day Saints]. There I learned much about human nature and saw much misery and suffering, mostly caused by dysfunctional relationships between people, especially in families. I decided I would study psychology and become a family counselor, to help alleviate the hurt I saw all around me.

I returned home to France in 2000, and shortly thereafter met my wife Anne-Marie while chatting on ICQ. We discovered we had similar interests, beliefs and values, and within 2 weeks (!?) I proposed to her over the Internet. I hadn't yet seen a picture of her. To me, physical appearance was not a concern.

She came over to France 6 (long!) months later, and we were married in France (civilly) and in England (for eternity in the Temple). A few months later we moved to England for a job which did not work out as expected, following which we moved to Western Australia in 2001.

==University and Self-teaching==
There I started taking interest in Web Development as a hobby (I had already built a couple of static websites as a youth), and used the many resources available online to teach myself LAMP/WAMP development. When I started my psychology degree (externally at Edith Cowan University), I chose a minor in professional computing, which included Object-Oriented programming, Database design and Web Development, but these added little to the knowledge I had already gained through learning online. The vibrant PHP community was the greatest source of learning for me.

A few years ago I undertook my first serious open source project with two other friends, Christopher Vance and Vickie Comrie (both from the USA). The project was a PHP auction framework, along the lines of Ebay but much more simple, which could be implemented by small companies wanting an auction system. It was a voluntary project for a fairly large american charity. This project hasn't been maintained for years, and I would probably cringe if I looked at the source code now, but the skills I learned while working on it have proven invaluable.

The code for the auction project attracted the attention of a small web development company, Triangle Solutions, who contracted me immediately on a part-time basis, later to become full-time. During the 1.5 years I worked for Triangle, I contributed to many different projects, but the most important was PHP Support Tickets, an application originally written in horrible spaghetti PHP which I was asked to upgrade. My decision was to rewrite it using Object-Oriented principles, of which I knew enough to improve the application at the time. Unfortunately I did not have the time resources available to devote enough time on this project, which greatly hindered its development. I still think it has great potential, but I would certainly refactor it if I had the opportunity to work on it again.

==Beginnings at Moodle HQ==
In December 2006, I applied for the developer position at Moodle HQ in Perth, and was hired on a full-time basis. I started out doing mainly bug-squashing for version 1.8, but was also made responsible for unit testing, an area which had been greatly neglected until then. As soon as 1.8 was stable and released, I started working on the new gradebook internals for 1.9, together with Yu Zhang, Martin Dougiamas and Petr Skoda.

==Other programming interests==
=== Ruby ===
One last note on development: I have recently taken great interest in the Ruby language, although that interest started much earlier than the current Ruby on Rails craze. I find the language extremely elegant, intuitive and fun to write in. It enables me to be much more creative than with PHP or Java. I also enjoy the Rails framework, although it certainly isn't as easy to learn as some people would have you believe. I am currently working on a real estate application (sales and rentals) written on that platform. You can see the front-end for one of my clients at [http://www.glenmarrealty.com.au Glenmar Realty].

=== Test-Driven Development (TDD) ===
Since my early days with Object-Oriented languages, I have been a strong proponent of unit testing, and a keen supporter of the Test-Driven Development approach. Unfortunately it is not always easy to adopt such methodology when working on a project like Moodle, with much legacy and non-OO code. The approach was successfully used when developing the new gradebook for Moodle 1.9, although it could have used better.

In the last 6 months I have given 3 presentations on the subject of Unit Testing. One was at the [http://elearning.lse.ac.uk/blogs/clt/?p=251 2007 UK Moodle Moot], and the other two were given at two different branches of the BCS, [http://nottmderby.bcs.org/events08-feb.htm Derby-Nottingham] and [http://www.herts.bcs.org/past.htm Hertfordshire]. [http://moodlemoot.org/file.php/4/moddata/assignment/1/438/presentation.ppt My slides] are available at these sites, but there are minor differences between them, since I try to improve my presentation each time.

==Psychology==
On the topic of psychology: during my external studies, I became more and more disillusioned with the traditional counseling practice. I felt that, although the intentions of most professional psychologists were noble, their skills were often exercised within an ideological framework of manufactured needs. This meant that often, their contributions to the well-being of the human race were more imagined than real.

My interests diverged towards community development, group processes, interpersonal relationships, child development and the learning process. I became aware that people tended to get better emotionally when they had a strong support network, and that non-professional assistance in the form of support groups was often more effective than prohibitory and extensive therapy sessions.

I also became more and more disenchanted with the educational practices of the universities in Australia. They seemed to be based on ancient traditions and to ignore the very principles they were teaching. I especially abhorred the lecture medium of teaching, which was one reason why I chose to study externally. However I did a few units on campus and was glad to see some tutors trying to change their delivery methods to something more informal and participative. Overall I was extremely disappointed in the appalling quality of external teaching. It was extremely difficult to connect with other students, and you only got help if you persistently sought for it. Feedback was as rare (and precious) as gold. BlackBoard was inadequate in many ways, and most tutors didn't even use it. The drop-out rates from external courses was so great that it was very difficult to extract that figure from university staff. I wouldn't be surprised if only around 10% of all external students across all Australian universities actually stuck to their entire course, not to mention those who stay but fail.

My project for the honours degree (which I have delayed for next year) was to compare the teaching methods of a German university with those of Edith Cowan University, and to compare the measurable results. The project for my doctorate was to develop an online, open source software suite that would enable external students to connect with each other as a vibrant community, in order to facilitate self-motivated learning and participation. This was a major factor in me accepting the job with Moodle, which represented exactly what I had in mind.

Well, this is a rather lengthy description, but those that have read all of it now know a lot about me, and will be better able to understand the person behind the posts and the code.

Blog 2.0

2009-10-22T23:44:22Z

Nicolasconnault: /* External blogs */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

Before 2.0 there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this could lead to serious performance and usability issues on large sites, and was turning the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

This simplification means that sites using the old BLOG_GROUP_LEVEL and BLOG_COURSE_LEVEL and values of $CFG->bloglevel have to perform an special upgrade which copies all the site's blog entries into a special "blog-type" forum in each course in which the blog entry's author is enrolled, then disables blogging at site level.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with an activity module.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can specify external blogs which publish an RSS/ATOM feed. This feed is then checked periodically through a cron task, and entries are copied into the user's blog in Moodle, as read-only entries.

This synchronisation checks if external entries have been modified or deleted since the last sync, and updates the Moodle entries accordingly.

These external blogs are a user preference, and two types of tags can be added to each of them: "Filter tags" and "Automatic tags":
*Filter tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog. An external entry will be selected if it has at least one of the filter tags. (Tags are called "categories" in RSS feeds)
*Automatic tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

Capabilities:
*moodle/blog:search

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

===Upgrade from "Users can only see blogs for people who share a course"===

This mode was always a slightly quirky and uncomfortable hack. It was mostly useful for sites with very distinct courses and users, such as those where each course consists of the employees from a separate company, and My Moodle was used to hide the companies from each other. However, for the general case, the main problem is that you see ALL blog entries from those people, not just ones that are about your courses.

This mode has no direct equivalent in Moodle 2.0 because we have resolved not to emulate "course-like" modes within a system that is at system level, and outside the courses. This helps understanding of the blog system, simplifies the implementation and improves performance.

However some people may be using that mode so we do need to provide an upgrade path for them.

Informationally, the idea of just seeing all the blogs from people who are in your course is the same as a course forum.

So a possible upgrade would be to do this:
If the mode is set to "Users can only see blogs for people who share a course" then
Set the new mode to "Users can only see their own blog"
Foreach user who has a blog
Foreach course that user is enrolled in
If a "Course blogs (recovered)" forum doesn't exist yet in the course (section 0) then create one
Foreach blog entry that the user created
Create a new discussion from the blog post with the same dates, attachments etc

This way no data is lost. The teachers can choose to delete the whole forum if they choose to. The original blog entries should not be touched.

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| failedlastsync
| int(1)
|
| Whether or not the last synchronisation failed
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-10-22T08:56:15Z

Nicolasconnault: /* blog_external */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

Before 2.0 there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this could lead to serious performance and usability issues on large sites, and was turning the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

This simplification means that sites using the old BLOG_GROUP_LEVEL and BLOG_COURSE_LEVEL and values of $CFG->bloglevel have to perform an special upgrade which copies all the site's blog entries into a special "blog-type" forum in each course in which the blog entry's author is enrolled, then disables blogging at site level.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with an activity module.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

Capabilities:
*moodle/blog:search

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

===Upgrade from "Users can only see blogs for people who share a course"===

This mode was always a slightly quirky and uncomfortable hack. It was mostly useful for sites with very distinct courses and users, such as those where each course consists of the employees from a separate company, and My Moodle was used to hide the companies from each other. However, for the general case, the main problem is that you see ALL blog entries from those people, not just ones that are about your courses.

This mode has no direct equivalent in Moodle 2.0 because we have resolved not to emulate "course-like" modes within a system that is at system level, and outside the courses. This helps understanding of the blog system, simplifies the implementation and improves performance.

However some people may be using that mode so we do need to provide an upgrade path for them.

Informationally, the idea of just seeing all the blogs from people who are in your course is the same as a course forum.

So a possible upgrade would be to do this:
If the mode is set to "Users can only see blogs for people who share a course" then
Set the new mode to "Users can only see their own blog"
Foreach user who has a blog
Foreach course that user is enrolled in
If a "Course blogs (recovered)" forum doesn't exist yet in the course (section 0) then create one
Foreach blog entry that the user created
Create a new discussion from the blog post with the same dates, attachments etc

This way no data is lost. The teachers can choose to delete the whole forum if they choose to. The original blog entries should not be touched.

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| failedlastsync
| int(1)
|
| Whether or not the last synchronisation failed
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-10-22T08:52:04Z

Nicolasconnault: /* blog_external */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

Before 2.0 there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this could lead to serious performance and usability issues on large sites, and was turning the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

This simplification means that sites using the old BLOG_GROUP_LEVEL and BLOG_COURSE_LEVEL and values of $CFG->bloglevel have to perform an special upgrade which copies all the site's blog entries into a special "blog-type" forum in each course in which the blog entry's author is enrolled, then disables blogging at site level.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with an activity module.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

Capabilities:
*moodle/blog:search

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

===Upgrade from "Users can only see blogs for people who share a course"===

This mode was always a slightly quirky and uncomfortable hack. It was mostly useful for sites with very distinct courses and users, such as those where each course consists of the employees from a separate company, and My Moodle was used to hide the companies from each other. However, for the general case, the main problem is that you see ALL blog entries from those people, not just ones that are about your courses.

This mode has no direct equivalent in Moodle 2.0 because we have resolved not to emulate "course-like" modes within a system that is at system level, and outside the courses. This helps understanding of the blog system, simplifies the implementation and improves performance.

However some people may be using that mode so we do need to provide an upgrade path for them.

Informationally, the idea of just seeing all the blogs from people who are in your course is the same as a course forum.

So a possible upgrade would be to do this:
If the mode is set to "Users can only see blogs for people who share a course" then
Set the new mode to "Users can only see their own blog"
Foreach user who has a blog
Foreach course that user is enrolled in
If a "Course blogs (recovered)" forum doesn't exist yet in the course (section 0) then create one
Foreach blog entry that the user created
Create a new discussion from the blog post with the same dates, attachments etc

This way no data is lost. The teachers can choose to delete the whole forum if they choose to. The original blog entries should not be touched.

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| validationresult
| int(1)
|
| A cached boolean of the last Feed validation test
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-10-15T03:02:29Z

Nicolasconnault: /* Who can view blog entries? */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

Before 2.0 there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this could lead to serious performance and usability issues on large sites, and was turning the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

This simplification means that sites using the old BLOG_GROUP_LEVEL and BLOG_COURSE_LEVEL and values of $CFG->bloglevel have to perform an special upgrade which copies all the site's blog entries into a special "blog-type" forum in each course in which the blog entry's author is enrolled, then disables blogging at site level.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with an activity module.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

Capabilities:
*moodle/blog:search

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

===Upgrade from "Users can only see blogs for people who share a course"===

This mode was always a slightly quirky and uncomfortable hack. It was mostly useful for sites with very distinct courses and users, such as those where each course consists of the employees from a separate company, and My Moodle was used to hide the companies from each other. However, for the general case, the main problem is that you see ALL blog entries from those people, not just ones that are about your courses.

This mode has no direct equivalent in Moodle 2.0 because we have resolved not to emulate "course-like" modes within a system that is at system level, and outside the courses. This helps understanding of the blog system, simplifies the implementation and improves performance.

However some people may be using that mode so we do need to provide an upgrade path for them.

Informationally, the idea of just seeing all the blogs from people who are in your course is the same as a course forum.

So a possible upgrade would be to do this:
If the mode is set to "Users can only see blogs for people who share a course" then
Set the new mode to "Users can only see their own blog"
Foreach user who has a blog
Foreach course that user is enrolled in
If a "Course blogs (recovered)" forum doesn't exist yet in the course (section 0) then create one
Foreach blog entry that the user created
Create a new discussion from the blog post with the same dates, attachments etc

This way no data is lost. The teachers can choose to delete the whole forum if they choose to. The original blog entries should not be touched.

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-10-15T02:45:30Z

Nicolasconnault: /* Associations */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with an activity module.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

Capabilities:
*moodle/blog:search

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

===Upgrade from "Users can only see blogs for people who share a course"===

This mode was always a slightly quirky and uncomfortable hack. It was mostly useful for sites with very distinct courses and users, such as those where each course consists of the employees from a separate company, and My Moodle was used to hide the companies from each other. However, for the general case, the main problem is that you see ALL blog entries from those people, not just ones that are about your courses.

This mode has no direct equivalent in Moodle 2.0 because we have resolved not to emulate "course-like" modes within a system that is at system level, and outside the courses. This helps understanding of the blog system, simplifies the implementation and improves performance.

However some people may be using that mode so we do need to provide an upgrade path for them.

Informationally, the idea of just seeing all the blogs from people who are in your course is the same as a course forum.

So a possible upgrade would be to do this:
If the mode is set to "Users can only see blogs for people who share a course" then
Set the new mode to "Users can only see their own blog"
Foreach user who has a blog
Foreach course that user is enrolled in
If a "Course blogs (recovered)" forum doesn't exist yet in the course (section 0) then create one
Foreach blog entry that the user created
Create a new discussion from the blog post with the same dates, attachments etc

This way no data is lost. The teachers can choose to delete the whole forum if they choose to. The original blog entries should not be touched.

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-30T07:12:00Z

Nicolasconnault: /* Search blog entries */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

Capabilities:
*moodle/blog:search

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-30T07:00:56Z

Nicolasconnault: /* Who can view blog entries? */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-30T07:00:03Z

Nicolasconnault: /* External blogs */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-30T06:59:11Z

Nicolasconnault: /* Associations */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Using the File API in Moodle forms

2009-09-25T08:48:49Z

Nicolasconnault: Add section on gotchas

{{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 "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, 'filetypes' => '*'));
</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, 'filetypes' => 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 0) 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.
;filetypes:(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/file/file_types.mm moodle/lib/file/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, '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, '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, '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, '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, 'filearea' => 'glossary_entry'));
</code>
The editor element can take following options: maxfiles, maxbytes, filearea, 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, '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, 'glossary_entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, '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/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/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, 'glossary_entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, '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, 'glossary_entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, '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

{{CategoryDeveloper}}
[[Category:Files]]
[[Category:Repositories]]

Using the File API in Moodle forms

2009-09-25T08:35:10Z

Nicolasconnault: /* Preparing your options */

{{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 "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, 'filetypes' => '*'));
</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, 'filetypes' => 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 0) 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.
;filetypes:(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/file/file_types.mm moodle/lib/file/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, '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, '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, '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, '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, 'filearea' => 'glossary_entry'));
</code>
The editor element can take following options: maxfiles, maxbytes, filearea, 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, '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, 'glossary_entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, '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/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/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, 'glossary_entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, '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, 'glossary_entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, '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

== See also ==

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

{{CategoryDeveloper}}
[[Category:Files]]
[[Category:Repositories]]

Using the File API in Moodle forms

2009-09-25T07:42:02Z

Nicolasconnault: /* Submitted data handling */

{{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 "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, 'filetypes' => '*'));
</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, 'filetypes' => 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 0) 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.
;filetypes:(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/file/file_types.mm moodle/lib/file/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, '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, '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, '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, '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, 'filearea' => 'glossary_entry'));
</code>
The editor element can take following options: maxfiles, maxbytes, filearea, 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, '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, 'glossary_entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, '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/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/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('trusttext'=>true, '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, 'glossary_entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, '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, 'glossary_entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, '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

== See also ==

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

{{CategoryDeveloper}}
[[Category:Files]]
[[Category:Repositories]]

Using the File API in Moodle forms

2009-09-25T07:38:14Z

Nicolasconnault: /* Element preparation */

{{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 "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, 'filetypes' => '*'));
</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, 'filetypes' => 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 0) 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.
;filetypes:(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/file/file_types.mm moodle/lib/file/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, '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, '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, '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, '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, 'filearea' => 'glossary_entry'));
</code>
The editor element can take following options: maxfiles, maxbytes, filearea, 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, '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, 'glossary_entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, '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/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/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('trusttext'=>true, '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, 'glossary_entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, '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

=== Submitted data handling ===
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, 'glossary_entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, '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

== See also ==

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

{{CategoryDeveloper}}
[[Category:Files]]
[[Category:Repositories]]

Using the File API in Moodle forms

2009-09-25T07:37:02Z

Nicolasconnault: Adding a conversion tutorial

{{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 "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, 'filetypes' => '*'));
</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, 'filetypes' => 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 0) 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.
;filetypes:(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/file/file_types.mm moodle/lib/file/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, '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, '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, '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, '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, 'filearea' => 'glossary_entry'));
</code>
The editor element can take following options: maxfiles, maxbytes, filearea, 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, '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, 'glossary_entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, '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/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/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('trusttext'=>true, '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, 'glossary_entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, '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

=== Submitted data handling ===
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, 'glossary_entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context, '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

== See also ==

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

{{CategoryDeveloper}}
[[Category:Files]]
[[Category:Repositories]]

File API

2009-09-25T06:34:57Z

Nicolasconnault: Putting link to more useful doc

{{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.
* A file area type, for example 'course_intro' or 'forum_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 is the course id. 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 core code must not access module or block files directly.

===Naming file areas===

It is important that file areas are named consistently so we do not get name collisions, and so the names are easy to understand. Please follow the following guidelines:

====start of the name====

If the file area belongs to a plugin, please use the plugin name as the start of the file area name.

This is the same plugin name that you would use for get_string calls. Some examples:
* All file areas that belong to the forum modules should have a name beginning with 'forum'. For example 'forum_post', 'forum_intro'.
* A file area belonging to the HTML block would start 'block_html_'.
* A file area belonging to a question type would start 'qtype_myqtype_', except this is probably not necessary, because question type images should probably be stored in the core 'question_text' file area.
* If the file area is used by a local hack, the file area name should start 'local_'.

If the file area belongs to core code, the file area name should start with a prefix that indicates what part of Moodle it belongs to.

But try to avoid clashing with prefixes that a plugin might use. Some examples:
* 'course_intro'
* 'question_text'
* 'user_draft' (although draft file areas are a special case).

====rest of the name====

Like naming variables or functions, try to find a name that is short, but says exactly what the file area is for.

If possible use the name of the file area to give a clue as to which database table the itemid relates to. For example:

* For the 'forum_post' file area, the itemid links to forum_post.id.
* For 'question_text' file area, the itemid links to question.id. (Would it be permissible to call this file area just question?)

==Serving files to users==

You must refer to the file with a URL that includes a file-serving script, often pluginfile.php. For example
<code php>
$url = $CFG->wwwroot/pluginfile.php/$contextid/$filearea/$itemid/file/path.ext;
</code>
Often you get these URLs generated automatically for you using the function file_rewrite_pluginfile_urls.

==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, $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, 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, 'filearea'=>'course_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===
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, $filearea, $fileitemid, $filepath, $filename);
// copy this file to draft area
$file_info->copy_to_storage($user_context->id, 'user_draft', $newitemid, '/', $title);
</code>

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

==See also==

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

[[Category:Files]]

File API internals

2009-09-25T06:15:55Z

Nicolasconnault: Updated name of fileareas

{{Moodle_2.0}}
This specification has now largely been implemented in Moodle 2.0. Inevitably, in the implementation, some details may have changed. If in doubt, read the code. (Then come back and correct this page ;-))

The implementation of this specification is being tracked at MDL-14589.

Please see [[Using the file API]] if you just want to know how to use the File API in your code, rather than how it works internally.

==Objectives==

The goals of these changes are to:

* allow files to be stored within Moodle, as part of the content (as we do now).
* use a consistent and simple approach for all file handling throughout Moodle.
* give modules control over which users can access a file, using capabilities and other local rules.
* make it easy to determine which parts of Moodle use which files, to simplify operations like backup and restore.
* track where files originally came from.
* avoid redundant storage, when the same file is used twice.
* fully support Unicode file names, irrespective of the capabilities of the underlying file system.

==Overview==

The File API is a set of core interfaces to allow the rest of Moodle to:
# store files, and
# display files to users.
It applies only to files that are part of the Moodle site's content. It is not used for internal files, such as those in the following subdirectories of dataroot: temp, lang, cache, environment, filter, search, sessions, upgradelogs, ...

The API can be subdivided into the following parts:
; Serving files
: Lets users accessing a Moodle site get the files (file.php, draftfile.php, pluginfile.php, userfile.php, etc.)
:* Serve the files on request
:* with appropriate security checks
; File API internals
: Stores the files on disc, with metadata in associated database tables.
:* Content-addressed storage.
; File management API
: Allows code to manipulate the stored files (lib/filelib.php)
:* find information about stored files.
:* print links to files.
:* move/rename/copy/delete/etc.
:* keep a file synchronised with an external repository.
; File management user interface
: Provides the interface for (lib/form/file.php, filemanager.php, filepicker.php and files/index.php, draftfiles.php)
:* Form elements allowing users to select a file using the Repository API, and have it stored within Moodle.
:* UI for users to manage their files, replacing the old course files UI

== Serving files ==

TODO revise this section.

Deals with serving of files - browser requests file, Moodle sends it back. We have three main files. It is important to setup slasharguments on server (file.php/some/thing/xxx.jpg), any content that relies on relative links can not work without it (scorm, uploaded html pages, etc.).

=== file.php ===

Serves course files.

Implements basic file access. Ideally only images and files linked from course sections should be there, no XSS protection required - we expect javascript, sw, etc. there, no way to make it "secure". The access control is not critical any more if we move most of the files into modules

The file name and parameter structure is critical for backwards compatibility of existing course content.

/file.php/courseid/dir/dir/filename.ext

Internally the files would be stored in <code>array('contextid'=>$coursecontextid, 'filearea'=>'coursefiles', 'itemid'=>0)</code>

=== pluginfile.php ===

(aka modfile.php)
Sends module, block, question files.
* modules decide about access control
* optional XSS protection - student submitted files must not be served with normal headers, we have to force download instead; ideally there should be second wwwroot for serving of untrusted files
* only internal links to selected areas are supported - you can link images in summary area, but not the assignment submissions

Absolute file links need to be rewritten if html editing allowed in module. The links are stored internally as relative links. Before editing or display the internal link representation is converted to absolute links using simple str_replace() @@thipluginlink/summary@@/image.jpg --> /pluginfile.php/assignmentcontextid/intro/image.jpg, it is converted back to internal links before saving.

::Can the distinct file areas supported by one plugin be declared somehow in order add some information about them? For example, I think it can be interesting to declare:
::* assignment_summary:
::** relpath='intro'
::** userdata=false
::** anotherproperty=anothervalue
::* assignment_submission:
::** relpath='submission/@@USERID@@'
::** userdata=false
::** anotherproperty=anothervalue
::* and so on...
::And then, when the editor "receives" one "assignment_summary" areaname, if knows what to show and so on? Also that info could be useful to know, in backup & restore if some fileareas have to be processed or no (userdata=false). Or also, when reconstructing the links (str_replace() above). And will cause to have a well defined list of fileareas by module, instead of coding them in a free way (prone to errors). [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 16:35, 28 June 2008 (CDT)

::Something like this will be part of file management API, hardcoding this in file storage would make it less flexible imo [[User:Skodak|Skodak]]

::Yup, yup. Storage doesn't know anything but get/put files (nothing else). It's part of management, absolutely. [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 11:21, 29 June 2008 (CDT)

/pluginfile.php/contextid/areaname/arbitrary/params/or/dirs/filename.ext

pluginfile.php detects the type of plugin from context table, fetches basic info (like $course or $cm if appropriate) and calls plugin function (or later method) which does the access control and finally sends the file to user. ''areaname'' separates files by type and divides the context into several subtrees - for example ''summary'' files (images used in module intros), post attachments, etc.

==== Assignment example ====

/pluginfile.php/assignmentcontextid/intro/someimage.jpg
/pluginfile.php/assignmentcontextid/submission/submissionid/attachmentname.ext
/pluginfile.php/assignmentcontextid/extra/allsubmissionfiles.zip

::Uhm... all those files together? What's going to differentiate the "submission" path in the example above from the "summary" path? Is it supposed that the editor, or the filemanager won't allow , for example to pick-up one file from the "submission" area to be used in the summary of one assignment and only the "summary" area will be showed? That means multiple file managers by context and it's against the clean "one file manager per context" agreed below [[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 21:28, 26 June 2008 (CDT)
::Yes Eloy, the different areas (summary, submission) etc. have different uses, different access control. There are two types of file manager - the two pane file manager which lists all contexts+areas user may access, and minimalistic manager in html editor which shows only subset of areas from current plugin (because you can not link anything else).

====scorm example====

/pluginfile.php/scormcontextid/intro/someimage.jpg
/pluginfile.php/scormcontextid/content/revisionnumber/dir/somescormfile.js

The revision counter is incremented when any file changes in order to prevent caching problems. The lifetime should be adjustable in module settings.

====quiz example====

pluginfile.php/quizcontextid/intro/niceimage.jpg
pluginfile.php/quizcontextid/report/type/export.ods

====questions example====

pluginfile.php/SYSCONTEXTID/question/questionid/file.jpg

====blog example====
Blog entries or notes in general do not have context id (because they live in system context, SYSCONTEXTID below is the id of system context).
The note attachments are always served with XSS protection on, ideally we should use separate wwwroot for this. Access control can be hardcoded.

/pluginfile.php/SYSCONTEXTID/blog_attachment/blogentryid/attachmentname.ext

Internally stored in <code>array('contextid'=>SYSCONTEXTID, 'filearea'=>'blog_attachment', 'itemid'=>$blogentryid)</code>

/pluginfile.php/SYSCONTEXTID/blog_post/blogentryid/embeddedimage.ext

Internally stored in <code>array('contextid'=>SYSCONTEXTID, 'filearea'=>'blog_post', 'itemid'=>$blogentryid)</code>

====backup example====
It would be nice to have some special protection of backup files - new capabilities for backup file download, upload. Backups contain a lot of personal info, we could block restoring of backups from other sites too.

/pluginfile.php/coursecontextid/backup/backupfile.zip

Internally stored in <code>array('contextid'=>$coursecontextid, 'filearea'=>'backup', 'itemid'=>0)</code>

===userfile.php===
Personal file storage, intended as an online storage of work in progress like assignments before the submission.
* read/write own files only for now
* option to share with others later
* personal "websites" will not be supported (security)

/userfile.php/userid/dir/dir/filename.ext

===rssfile.php===
Replaces rss/file.php which is kept only for backwards compatibility.
RSS files should not require sessions/cookies, URLs should contain some sort of security token/key.
Internally the files may be stored in database or together with other files.
Performance improvements - we should support both Etag (cool) and Last-Modified (more used), when we receive If-None-Match/If-Modified-Since => 304

/rssfile.php/contextid/any/parameters/module/wants/rss.xml
/rssfile.php/SYSCONTEXTID/blog/userid/rss.xml

Again modules and plugins decide what gets sent to user.

=== Temporary files ===
Temporary files are usually used during the lifetime of one script only.
uses:
* exports
* imports
* zipping/unzipping
* processing by executable files (latex, mimetex)

Ideally these files should never use utf-8 (which is a major problem for zipping at the moment).
Proposed new sha1 based file storage is not suitable both for performance and technical reasons.

=== Legacy file storage and serving ===
Going to use good-old separate directories in $CFG->dataroot.

file serving and storage:
# user avatars - user/pix.php
# group avatars - user/pixgroup.php
# tex, algebra - filter/tex/* and filter/algebra/*
# rss cache (?full rss rewrite soon?) - backwards compatibility only rss/file.php

only storage:
#sessions

== File API internals ==

=== File storage on disk ===

Files are stored in $CFG->dataroot (also known as moodledata) in the filedir subfolder.

Files are stored according to the SHA1 hash of their content. This means each file with particular contents is stored once, irrespective of how many times it is included in different places, even if it is referred to by different names. (This idea comes from the git version control system.) To relate a file on disc to a user-comprehensible path or filename, you need to use the file database tables. See the next section.

Suppose a file has SHA1 hash 081371cb102fa559e81993fddc230c79205232ce. Then it will be stored in on disc as moodledata/filedir/08/13/71/081371cb102fa559e81993fddc230c79205232ce.

If you were wondering, in PHP, SHA1 hashes can be computed with either the [http://php.net/sha1 sha1] or [http://php.net/sha1_file sha1_file] functions.

The information in this section should be considered completely internal to the file API. Other parts of the Moodle code should manipulate files using the higher level functions of the file API. For example, they should refer to files by file id in the file table, not the SHA1 hash.

=== Files database tables ===

==== Table: files ====

This table contains one entry for each usage of a file. Enough information is kept here so that the file can be fully identified and retrieved again if necessary.

If, for example, the same image is used in a user's profile, and a forum post, then there will be two rows in this table, one for each use of the file, and Moodle will treat the two as separate files, even though the file is only stored once on disc.

{| class="nicetable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
| The unique ID for this file.
|-
| contenthash
| varchar(40)
|
| The sha1 hash of content.
|-
| pathnamehash
| varchar(40)
|
| The sha1 hash of contextid+filearea+itemid+filepath+filename - prevents file duplicates and allows fast lookup
|-
| '''contextid'''
| int(10)
|
| The context id defined in context table - identifies the instance of plugin owning the file.
|-
| filearea
| varchar(50)
|
| Like "submissions", "intro" and "content" (images and swf linked from summaries), etc.; "blogs" and "userfiles" are special case that live at the system context.
|-
| '''itemid'''
| int(10)
|
| Some plugin specific item id (eg. forum post, blog entry or assignment submission or user id for user files)
|-
| filepath
| text
|
| relative path to file from module content root, useful in Scorm and Resource mod - most of the mods do not need this
|-
| filename
| varchar(255)
|
| The full Unicode name of this file (case sensitive)
|-
| '''filesize'''
| int(10)
|
| size of file - bytes
|-
| mimetype
| varchar(100)
| NULL
| type of file
|-
| '''userid'''
| int(10)
| NULL
| Optional - general user id field - meaning depending on plugin
|-
| '''timecreated'''
| int(10)
|
| The time this file was created
|-
| '''timemodified'''
| int(10)
|
| The last time the file was last modified
|}

Indexes:
* non-unique index on (contextid, filearea, itemid)
* non-unique index on (contenthash)
* unique index on (pathnamehash).

The plugin type does not need to be specified because it can be derived from the context. Items like blog that do not have their own context will use their own file area inside a suitable context. In this case, the user context.

Entries with filename = '.' represent directories. Directory entries like this are created automatically when a file is added within them.

Note: 'files' plural used even thought that goes against the [[Database|coding guidelines]] because 'file' is a reserved word.

==== Table: files_metadata ====

This table contains extra metadata about files. Repositories could provide this, or it could be manually edited in the local copy.

{| class="nicetable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''fileid'''
| int(10)
|
| Foreign key, references files.id
|-
| '''name'''
| varchar(255)
|
| The name of the metadata field
|-
| value
| text
|
| The value of this metadata field
|}

Note: this is not implemented yet.

==== Table: files_sync ====

This table contains information on how to synchronise data with repositories. Data would be synchronised from cron.php or on demand from file manager. The sync would be one way only (repository -> local file).

{| class="nicetable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''fileid'''
| int(10)
|
| Foreign key, references files.id
|-
| '''repositoryid'''
| int(10)
|
| The repository instance this is associated with, see [[Repository_API]]
|-
| updates
| int(10)
|
| Specifies the update schedule (0 = none, 1 = on demand, other = some period in seconds)
|-
| repositorypath
| text
|
| The full path to the original file on the repository
|-
| timeimportfirst
| int(10)
|
| The first time this file was imported into Moodle
|-
| timeimportlast
| int(10)
|
| The most recent time that this file was imported into Moodle
|}

Note: this is not implemented yet. It may end up being implemented within the Repository API istead. That is, this table may end up being called repository_sync.

==== Table: files_cleanup ====

This table contains candidates for deletion from the file pool. Files are not deleted immediately because there may be multiple references to the same file. Therefore, it is better for performance to simply add a row to this table, and later, on cron, clean the files off disc if they are really no longer used. Also, batch deletion on cron makes it easier to avoid concurrency issues when one user deletes what was the last reference to the file as another user adds a new reference. (The cron cleanup code should be doing appropriate locking.)

{| class="nicetable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| contenthash
| varchar(40)
|
|
|}

===Implementation of basic operations===

This is just an overview. See the external API description below for how to do this from client code.

====Storing a file====

# Calculate the SHA1 hash of the file contents.
# Check if a file with this SHA1 hash already exists on disc. If not, store the file there.
# Remove this SHA1 hash from list of deleted files, if present.
# Add the record for this file to the files table.

====Reading a file====

# Fetch the record (which includes the SHA1 hash) for the file you want from the files table.
# Retrieve the contents using the SHA1 hash.

====Deleting a file====

# Store the SHA1 hash of the file being deleted in the files_cleanup table.
# Delete the record from the files table.
# Later, admin/cron.php will actually delete the file from disc if it is no longer used (with proper table locking to prevent race conditions when adding/deleting files simultaneously).

== File browsing and management API ==

This is what other parts of Moodle use to access and manage files. The code is in lib/file/.

These section documents both the public facing parts of this code, and also the inner workings. Hopefully it makes it sufficiently clear which is which. For more information, see the API documentation in the code, and [[Using_the_file_API]].

TODO write the rest of this section.

=== lib/filelib.php ===

Including this file includes all of the other library files.

=== Class: file_browser ===

=== Class: file_info and subclasses ===

=== Class: file_storage ===

=== Class: stored_file ===

=== File exceptions===

== File management user-interface ==

=== File manager ===

All the contexts, file areas and files now form a single huge tree structure, although each user only has access to certain parts of that tree. The file manager (files/index.php) allow users to brows this tree, and manage files within it, according to the level of permissions they have.

Single pane file manager is hard to implement without drag & drop which is notoriously problematic in web based applications. I propose to implement a two pane commander-style file manager. Two pane manager allows you to easily copy/move files between two different contexts (ex: courses).

File manager must not interact directly with filesystem API, instead each module should return traversable tree of files and directories with both real and localised names (localised names are needed for dirs like backupdata).

This code will be in file/.

=== Formslib field types ===

This code will be in lib/form/

* Upload single files.
* Upload multiple files to a files area.
* HTML editor (see next)

=== Integration with the HTML editor ===

Each instance of the HTML editor will be told to store related files in a particular file area.

During editing, files will be stored in a draft files area. Then when the form is submitted they will be (automatically) moved into the real file area.

Files will be selected using the repository file picker.

=== Local files repository plugin ===

Allows users to see an browse files they already have access to within this Moodle, for inclusion in the page currently being edited.

This code will be in repository/local/

== Backwards compatibility ==

=== Content backwards compatibility ===

This should be preserved as much as possible. This will involve rewriting links in content during the upgrade to 2.0.

Some new features (like resource sharing - if implemented) may not work with existing data that still uses files from course files area.

There might be a breakage of links due to special characters stripping in uploaded files which will not match the links in uploaded html files any more. This should not be very common I hope.

===Code backwards compatibility===

Other Moodle code (for example plugins) will have to be converted to the new APIs. See [[Using_the_file_API]] for guidance.

It is not possible to provide backwards-compatibility here. For example, the old $CFG->dataroot/$courseid/ will no longer exist, and there is no way to emulate that, so we won't try.

== Upgrade and migration ==

When a site is upgraded to Moodle 2.0, all the files in moodledata will have to be migrated. This is going to be a pain, like DML/DDL was :-(

The upgrade process should be interruptible (like the Unicode upgrade was) so it can be stopped/restarted any time.

=== Migration of content ===

* resources - move files to new resource content file area; can be done automatically for pdf, image resources; definitely not accurate for uploaded web pages
* questions - image file moved to new area, image tag appended to questions
* moddata files - the easiest part, just move to new storage
* coursefiles - there might be many outdated files :-( :-(
* rss feeds links in readers - will be broken, the new security related code would break it anyway

=== Moving files to files table and file pool ===

The migration process must be interruptable because it might take a very long time. The files would be moved from old location, the restarting would be straightforward.

Proposed stages:
#migration of all course files except moddata - finish marked by some $CFG->files_migrated=true; - this step breaks the old file manager and html editor integration
#migration of blog attachments
#migration of question files
#migration of moddata files - each module is responsible to copy data from converted coursefiles or directly from moddata which is not converted automatically

Some people use symbolic links in coursefiles - we must make sure that those will be copied to new storage in both places, though they can not be linked any more - anybody wanting to have content synced will need to move the files to some repository and set up the sync again.

::Talked about a double task here, when migrating course files to module areas:
::# Parse html files to detect all the dependencies and move them together.
::# Fallback in pluginfile.php so, if something isn't found in module filearea, search for it in course filearea, copying it and finally, serving it.

:: Also we talked about the possibility of add a new setting to resource in order to define if it should work against old coursefiles or new autocontained file areas. Migrated resources will point to old coursefiles while new ones will enforce autocontained file areas.

:: it seems that only resource files will be really complex (because allow arbitrary HTML inclusion). The rest (labels, intros... doesn't) and should be easier to parse.

::[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 19:00, 29 June 2008 (CDT)

== Parts of Moodle that need to be modified ==

Of course, all parts of Moodle that use files need to be changed. See MDL-14589 for a more detailed list.

=== Any form where the user can upload files ===

=== Any from containing a HTML editor ===

Since users can embed images etc. there.

=== Backup/restore ===

File handling in backups needs to be fully rewritten - list of files in xml + pool of sha1 named files with contents. This solves the utf-8 trouble here, yay!!

=== Antivirus scanning ===

== Issues that need to be resolved ==

=== Unicode support in zip format ===

''This has now been solved by using the built in zip in PHP 5.2.8.''

Zip format is an old standard for compressing files. It was created long before Unicode existed, and Unicode support was only recently added. There are several ways used for encoding of non-ASCII characters in path names, but unfortunately it is not very standardised. Most Windows packers use DOS encoding.

Client software:
* Windows built-in compression - bundled with Windows, non-standard DOS encoding only
* WinZip - shareware, Unicode option (since v11.2)
* TotalCommander - shareware, single byte(DOS) encoding only
* 7-Zip - free, Unicode or DOS encoding depending on characters used in file name (since v4.58beta)
* Info-ZIP - free, uses some weird character set conversions

PHP extraction:
* Info-ZIP binary execution - no Unicode support at all, mangles character sets in file names (depends on OS, see docs), files must be copied to temp directory before compression and after extraction
* PclZip PHP library - reads single byte encoded names only, problems with random problems and higher memory usage.
* Zip PHP extension - reads single byte encoded names only, 64bit operating system can not open/create archives with more than 500 files (depends on sum of lengths of all filenames and directories, to be fixed in PHP 5.3 and external PECL library, no PHP 5.2.x backport planned!), adding of files is limited by number of free file handles (around 1000 - depends on OS and other PHP code, workaround is to close and reopen archive)

Large file support:
PHP running under 32bit operating systems does not support files >2GB (do not expect fix before PHP 6). This might be a potential problem for larger backups.

Tar Alternative:
* tar with gzip compression - easy to implement in PHP + zlib extension (PclTar, Tar from PEAR or custom code)
* no problem with unicode in *nix, Windows again expects DOS encoding :-(
* seems suitable for backup/restore - yay!

Roadmap:
# add zip processing class that fully hides the underlying library
# use single byte encoding "garbage in/garbage out" approach for encoding of files in zip archives; add new 'zipencoding' string into lang packs (ex: cp852 DOS charset for Czech locale) and use it during extraction, we might support true unicode later when PHP Zip extension does that

== Possible future ideas ==

=== Files maintenance report ===

This would do deep validation of the files on disc. It would:
* Report when there is a row in the files table, but the corresponding file is missing from the file system.
* Report files that still exist on disc, even though no references remain.
* Report orphaned files.
* Report total disc space usage by context (as much as is possible with content-addressible file storage).
* Verify that the SHA1 hash of the contents of each file matches the file name.

In addition, it might offer options to fix these problems, where possible.

=== Support quotas per user, course, etc. ===

People want this.

If we have implemented the above report, it would then just be a matter of adding the interface hooks to stop people uploading more files once the quota has been reached.

(We could also divide the file size by number of instances that are using it, this might be considered more accurate in some scenarios.)

== See also ==

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

{{CategoryDeveloper}}
[[Category:Files]]

[[ja:開発:ファイルAPI]]

Deprecated functions in 2.0

2009-09-24T09:21:41Z

Nicolasconnault:

{{Work in progress}}
{{Moodle 2.0}}

This page lists all functions that have been deprecated between 1.9 and 2.0, with instructions on how to upgrade your code. A count of remaining function calls in core is kept next to each function name.

== General notes ==

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (0) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (0) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->title = $title; // optional
$options['height'] = $height; // optional
$options['width'] = $width; // optional
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (0) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>

New code (with options in arrays):
<code php>
echo $OUTPUT->confirm($message, new moodle_url($linkyes, $optionsyes), new moodle_url($linkno, $optionsno));
</code>

New code (if the "get" method is required):
<code php>
$formcontinue = html_form::make_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = html_form::make_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

Note: $nocurr has been dropped. Current page number is never displayed as a link

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (0) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Migrating your code to the 2.0 rendering_API]]

{{CategoryDeveloper}}

Deprecated functions in 2.0

2009-09-24T09:20:33Z

Nicolasconnault: /* General notes */

{{Work in progress}}
{{Moodle 2.0}}

This page lists the old HTML-outputting functions of pre-2.0 lib/weblib.php and their 2.0 equivalents using $OUTPUT functions.

== General notes ==

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (0) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (0) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->title = $title; // optional
$options['height'] = $height; // optional
$options['width'] = $width; // optional
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (0) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>

New code (with options in arrays):
<code php>
echo $OUTPUT->confirm($message, new moodle_url($linkyes, $optionsyes), new moodle_url($linkno, $optionsno));
</code>

New code (if the "get" method is required):
<code php>
$formcontinue = html_form::make_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = html_form::make_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

Note: $nocurr has been dropped. Current page number is never displayed as a link

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (0) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Migrating your code to the 2.0 rendering_API]]

{{CategoryDeveloper}}

Outputting HTML in 2.0

2009-09-24T09:19:56Z

Nicolasconnault: Outputting HTML in 2.0 moved to Deprecated functions in 2.0: Expanding the use of this page for all deprecated functions

#REDIRECT [[Deprecated functions in 2.0]]

Deprecated functions in 2.0

2009-09-24T09:19:56Z

Nicolasconnault: Outputting HTML in 2.0 moved to Deprecated functions in 2.0: Expanding the use of this page for all deprecated functions

{{Work in progress}}
{{Moodle 2.0}}

This page lists the old HTML-outputting functions of pre-2.0 lib/weblib.php and their 2.0 equivalents using $OUTPUT functions.

== General notes ==
The principle of the new rendering API is to let the developer build metadata-rich components that ''represent'' HTML elements, but may be rendered in many different ways. A menu component, for example, could be rendered as a <select> element, or as a list of radio buttons or check boxes.

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected); // Required
$select->nothinglabel = $nothing;
$select->nothingvalue = $nothingvalue;
$select->disabled = $disabled;
$select->tabindex = $tabindex;
$select->id = $id;
$select->listbox = $listbox;
$select->multiple = $multiple;
$select->add_classes($class);

echo $OUTPUT->select($select);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (0) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (0) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->title = $title; // optional
$options['height'] = $height; // optional
$options['width'] = $width; // optional
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (0) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>

New code (with options in arrays):
<code php>
echo $OUTPUT->confirm($message, new moodle_url($linkyes, $optionsyes), new moodle_url($linkno, $optionsno));
</code>

New code (if the "get" method is required):
<code php>
$formcontinue = html_form::make_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = html_form::make_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
echo $OUTPUT->header($navigation, $menu);
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

Note: $nocurr has been dropped. Current page number is never displayed as a link

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (0) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Migrating your code to the 2.0 rendering_API]]

{{CategoryDeveloper}}

Talk:Blog 2.0

2009-09-24T08:44:25Z

Nicolasconnault: /* Some questions */

=== Some questions ===

* about the "who can view"/"externl blogs"/"associations" things... is going to be some capability like:
** viewblogentries
** viewdraftblogentries
** fetchexternalblogs
** searchblogentries
** associateblogentries
:Yes to the above [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
* Also, are "fetched" and manual blog entries differentiated in any way?
:In the database, entries that have been copied from an external blog will have a value in the post.uniquehash field. Also, you will be able to automatically tag an external blog's entries with one or more tags [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
* Finally, both tags and associations are going to be published in the RSS Feeds?
:I don't see why not, maybe that could be optional [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
* Is it going to be possible to get RSS Feeds by tag or association?
:Yes [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
* [http://en.wikipedia.org/wiki/Atom_(standard) ATOM] (import from external blog feeds / publish local feeds)
:Not sure, can you explain? [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
* When blog entries are displayed for say, course XX, will also "child" entries be displayed (activity-associated).
:Yes, whenever an entry is associated with an activity, it is also automatically associated with the course. [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
::"automatically associated" stands for: association record created automatically or rely in accesslib (nested contexts) abilities?
* If association is disabled in one site (or user if the capability exists), which will be the behaviour of the blocks?
:Instead of searching for entries associated with the course, it will just show all blog entries (for the site). The links in the blog_menu will be simplified accordingly. [[User:Nicolas Connault|Nicolas Connault]] 08:56, 22 September 2009 (UTC)
--[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 08:45, 22 September 2009 (UTC)

----

===More questions===
'''Who can view blog entries''' - the description is not correct, there were more access levels, we can not just remove them - please explain the differences and propose upgrade routes. The descriptions have to contain all relevant capabilities and their use.

'''Associations''' - just the context id does not seem to be granular enough, we use are+itemid elsewhere because it allows you to specify the exact forum discussion or post for example. Another problem is should we allow association with context you are not enrolled in? Please include all relevant capabilities too. ''blogid'' in blog_assoc table links which column and table? Should it be called postid?

'''External blogs''' I would not call it import, maybe better "sync with external blog". I suppose that it might be good to have a tag name in the blog description. There could be also separate option for synchronisation of external tags. Hmm, we could also fetch posts with some tags only. We do not need tags in order to distinguish external feeds - they have the hash there. The problem I see is if you accidentally add some ext blog and then you want to delete it - we do not know from which feed it was added (I suppose one user may have multiple ext blogs linked). Again include all caps.

'''Atom''' what is it ''atom write'' support?

'''Attachments''' we need embedded images too.

'''Problems'''
* different access control compared to 1.9
* RSS feeds when posts are not accessible without login need some form of protection

[[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 21:13, 22 September 2009 (UTC)

----

Talk:Blog 2.0

2009-09-22T08:56:05Z

Nicolasconnault: /* Some questions */

Blog 2.0

2009-09-22T08:46:15Z

Nicolasconnault: /* Description of improvements */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-22T08:08:51Z

Nicolasconnault:

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676 this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-22T08:01:59Z

Nicolasconnault: /* Upgrade process */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676 this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-22T08:00:14Z

Nicolasconnault: /* DB Structure */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676 this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-21T06:52:31Z

Nicolasconnault: /* Who can view blog entries? */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676 this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_associations

== Upgrade process ==

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-21T06:52:12Z

Nicolasconnault: /* Who can view blog entries? */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676 |this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_associations

== Upgrade process ==

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-21T06:48:14Z

Nicolasconnault: /* DB Structure */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676|this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==
2 new tables need to be added: blog_external and blog_associations

== Upgrade process ==

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-21T06:29:09Z

Nicolasconnault:

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public. (See [http://tracker.moodle.org/browse/MDL-19676|this tracker issue])

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: [http://tracker.moodle.org/browse/MDL-14408]

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.
Tracker issue: [http://tracker.moodle.org/browse/MDL-19683]

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19686]

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19687]

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19744]

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: [http://tracker.moodle.org/browse/MDL-8776]

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: [http://tracker.moodle.org/browse/MDL-19688]

== Potential problems and limitations ==

== DB Structure ==

== Upgrade process ==

== See also ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-21T06:24:43Z

Nicolasconnault: /* Other links and resources */

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public.

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

== Potential problems and limitations ==

== DB Structure ==

== Upgrade process ==

== Other links and resources ==
*[[Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-21T06:24:21Z

Nicolasconnault: Other links and resources

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': Link to forum discussion will appear here

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

At one stage in 2.0 development there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this would lead to serious performance and usability issues, and would turn the blog into something more akin to a forum. It was thus decided to make all blogs public.

An admin setting can allow for blog entries to be accessible by non-logged-in users, for the purpose of publishing and RSS feed aggregation.

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with activity modules, in which case the blog entry is automatically associated with the module's course.

This requires the creation of a new table, in which the associations are recorded.

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can import blog entries into Moodle from external blogs. The external blog's entries are copied into Moodle when the external blog URL is entered, and a cron task periodically checks these external blogs to copy new entries not yet entered in Moodle. The period of time between checks can be adjusted as an admin setting.

These external blogs are a user preference, and two types of tags can be added to each of them: "External tags" and "Moodle tags":
*External tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog.
*Moodle tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags. This makes it easier to distinguish which of a user's blog entries come from an external blog.

This requires the creation of a new DB table.

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

=== File attachments ===
The [[File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

=== Comments ===
The new [[Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

== Potential problems and limitations ==

== DB Structure ==

== Upgrade process ==

== Other links and resources ==
*[[https://docs.moodle.org/en/Development:Blogs|Early wishlist]]
*[[https://docs.moodle.org/en/Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

Blog 2.0

2009-09-21T06:20:48Z

Nicolasconnault: /* Description of improvements */

Blog 2.0

2009-09-21T06:16:08Z

Nicolasconnault: /* Description of improvements */

Blog 2.0

2009-09-21T06:14:13Z

Nicolasconnault: /* Description of improvements */

Blog 2.0

2009-09-21T06:08:30Z

Nicolasconnault: /* Description of improvements */

Blog 2.0

2009-09-21T06:04:46Z

Nicolasconnault: /* Description of improvements */

Blog 2.0

2009-09-21T05:59:42Z

Nicolasconnault: /* Description of improvements */