MoodleDocs - Contribucions de l'usuari [ca]

Moodle in education

2009-03-16T16:18:07Z

Davidkazuhiro: reverting to previous version

{{Teacher documentation}}
* '''[[Getting started for teachers|Getting started for teachers page link]]''' - New at this Moodle thing? The "Getting started" page gives a general overview of all the features of a course. There are lots of internal links that will allow you to expand your knowledge. Welcome !

You can get back to this page by using the Teacher link in the Documentation menu on the left on most MoodleDoc pages.

==Reference==
*[[:Category:Teacher]] - a list of links to "Teacher" related pages
*[[Moodle manuals]] - a list of links to manuals and books
*[[Using Moodle book]] - a real book you can reprint!

==Guidelines==
*[[Blogs]] - blogs in Moodle
*[[Teaching with Moodle]] - inspiring links
*[http://moodle.org/mod/forum/discuss.php?d=66854 Moodle and elearning intro] - Written by Martin Langhoff
*[[Teaching do's and don'ts|Teaching Do's and Don'ts]] - hints
*[[Teaching FAQ]] - common questions
*[http://moodle.tokem.fi/mod/book/view.php?id=16397&chapterid=8258 Example of a course teaching checklist]
*[http://moodle.tokem.fi/mod/book/view.php?id=16397 Teacher's Moodle Manual] - site specific, done in Moodle with the book module
*[http://www.houseoftutorials.net/ Video Tutorials on how to use Moodle] (go to the learning Moodle section and login as guest)
*[[Teaching tips and tricks]]
*[[Student documentation examples]]
*[[Student FAQ]] - students have questions about technology?
*[[Trainer]] - links that might be useful to Trainers
*Non Internet Moodles - useful for course building and sandboxes
:[[Complete install packages]] design course on your desktop
:[[Installation guide - Moodle for Windows on a USB Memory Stick]]
:[[Development:Windows_Installer_anywhere]]

[[Category:Teacher]]
[[cs:Rukověť učitele]]
[[de:Dokumentation für Trainer]]
[[es:Documentación para Profesores]]
[[eu:Irakasleentzako dokumentazioa]]
[[fi:Opettajan opas]]
[[fr:Documentation enseignant]]
[[it:Documentazione per Docenti]]
[[ja:教師ドキュメント]]
[[nl:Documentatie voor leraren]]
[[ru:Учителям]]
[[zh:教师文档]]

Broken/Blocks

2009-01-04T00:37:27Z

Davidkazuhiro: /* Configure That Out */ spelling

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou (pj@moodle.org)

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Blocks_Howto#appendix_b| Appendix B]]).
The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though. Experienced developers and those who just want a reference text should refer to [[Blocks_Howto#appendix_a| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==
Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required. Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardized and essential for Moodle to work correctly.
Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==
To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory <span class="filename">/blocks/simplehtml/</span> and creating a file named <span class="filename">/blocks/simplehtml/block_simplehtml.php</span> which will hold our code. We then begin coding the block:
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardized.
Our class is then given a small method: [[Blocks_Howto#method_init| init]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.
[[Blocks_Howto#variable_title| $this->title]] is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks_Howto#section_eye_candy| how to disable the title's display]].
[[Blocks_Howto#variable_version| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data. In our example,
this is certainly the case so we just set [[Blocks_Howto#variable_version| $this->version]] to '''YYYYMMDD00''' and forget about it.
'''UPDATING:''' Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
}
?>
It can't get any simpler than that, can it? Let's dissect this method to see what's going on...
First of all, there is a check that returns the current value of [[Blocks_Howto#variable_content| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.
At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it and after seeing it in action come back to continue our tutorial.

== Configure That Out ==
The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:
function instance_allow_config() {
return true;
}
This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: <span class="filename">/blocks/simplehtml/config_instance.html</span> (which has to be named exactly like that). For the moment, copy paste the following into it and save:
<nowiki>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>
<?php use_html_editor(); ?>
</nowiki>
It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our <span class="filename">config_instance.html</span> file as instance configuration data. We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.
You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Blocks_Howto#method_init| init]].
In the event where the default behavior is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Blocks_Howto#appendix_a| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Blocks_Howto#variable_config| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in its configuration data. To do that, find this snippet in <span class="filename">/blocks/simplehtml/block_simplehtml.php</span><nowiki>:</nowiki>

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';
and change it to:

$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:
<nowiki>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';</nowiki>
After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

== The Specialists ==
Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?
Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to <span class="filename">/blocks/simplehtml/config_instance.html</span>. Here goes:
<nowiki>
<tr valign="top">
<td align="right"><p><?php print_string('configtitle', 'block_simplehtml'); ?>:</p></td>
<td><input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" /></td>
</tr>
</nowiki>
We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.
That's not too wierd, if we think back a bit. Do you remember that [[Blocks_Howto#method_init| init]] method, where we set [[Blocks_Howto#variable_title| $this->title]]? We didn't actually change its value from then, and [[Blocks_Howto#variable_title| $this->title]] is definitely not the same as $this->config->title (to Moodle, at least). What we need is a way to update [[Blocks_Howto#variable_title| $this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks_Howto#variable_config| $this->config]] in all methods ''except'' [[Blocks_Howto#method_init| init]]<nowiki>! So what can we do?</nowiki>
Let's pull out another ace from our sleeve, and add this small method to our block class:

function specialization() {
if(!empty($this->config->title)){
$this->title = $this->config->title;
}
else{
$this->config->title = ''''''';
}
if(empty($this->config->text)){
$this->config->text = ''''''';
}
}
Aha, here's what we wanted to do all along! But what's going on with the [[Blocks_Howto#method_specialization| specialization]] method?
This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks_Howto#method_init| init]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks_Howto#method_specialization| specialization]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== Now You See Me, Now You Don't ==
Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. (An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists. However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful). It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.
This is indeed possible, and the way to do it is to make sure that after the [[Blocks_Howto#method_get_content| get_content]]<nowiki> method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (''). Moodle performs this check by calling the block's </nowiki>[[Blocks_Howto#method_is_empty| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.
Note that the exact value of the block's title and the presence or absence of a [[Blocks_Howto#method_hide_header| hide_header]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.
== We Are Legion ==
Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

function instance_allow_multiple() {
return true;
}
This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!
There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.
And finally, a nice detail is that as soon as we defined an [[Blocks_Howto#method_instance_allow_multiple| instance_allow_multiple]] method, the method [[Blocks_Howto#method_instance_allow_config| instance_allow_config]] that was already defined became obsolete. Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Blocks_Howto#method_instance_allow_config| instance_allow_config]] method now without harm. We had only needed it when multiple instances of the block were not allowed.
== The Effects of Globalization ==
Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with. For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.
This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

function has_config() {
return true;
}
Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file <span class="filename">/blocks/simplehtml/config_global.html</span> which again must be named just so, and copy paste the following into it:

<pre>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict)) echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>
<p><input type="submit" value="<?php print_string('savechanges'); ?>" /></p>
</div>
</pre>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean false) it displays the box as pre-checked (reflecting the current status). Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting. "block_simplehtml_strict" clearly satisfies both requirements.
The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?
Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.
However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.
To round our bag of tricks up, notice that the use of if(!empty($CFG->block_simplehtml_strict)) in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable $CFG->block_simplehtml_strict will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").
Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Blocks_Howto#method_config_save| config_save]], the default implementation of which is as follows:

function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}
else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).
So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?
We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.
Much as we did just before with overriding [[Blocks_Howto#method_config_save| config_save]], what is needed here is overriding the method [[Blocks_Howto#method_instance_config_save| instance_config_save]] which handles the instance configuration. The default implementation is as follows:

function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance', 'configdata', base64_encode(serialize($data)),
'id', $this->instance->id);
}
This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!
Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed. The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?
We will let this part of the tutorial come to a close with the obligatory excercise for the reader: in order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead. (Hint: do that in the [[Blocks_Howto#method_get_content| get_content]] method)
'''UPDATING'''<nowiki>: Prior to version 1.5, the file </nowiki><span class="filename">config_global.html</span> was named simply <span class="filename">config.html</span>. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== Eye Candy ==
Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.
First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

function hide_header() {
return true;
}
One more note here: we cannot just set an empty title inside the block's [[Blocks_Howto#method_init| init]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks_Howto#method_init| init]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.
Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.
To instruct Moodle about our block's preferred width, we add one more method to the block class:

function preferred_width() {
// The preferred value is in pixels
return 200;
}
This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.
Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we 'll see below).
The default behavior of this feature in our case will assign to our block's container the class HTML attribute with the value "sideblock block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").
To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example, the version

function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required). And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Blocks_Howto#method_name| name]] method to make it dynamically match our block's name.

== Authorized Personnel Only ==
It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.
Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.
Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.
The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:
#* The format name for the front page of Moodle is '''site-index'''.
#* The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
#* Even though there is no such page, the format name '''all''' can be used as a catch-all option.
We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":
#* Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
#* The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
#* The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
#* The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

function applicable_formats() {
return array('site' => true);
}
Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to true, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).
For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

function applicable_formats() {
return array('course-view' => true, 'course-view-social' => false);
}
This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

function applicable_formats() {
return array('site-index' => true,
'course-view' => true, 'course-view-social' => false,
'mod' => true, 'mod-quiz' => false);
}
It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.
'''UPDATING:''' Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.
== Lists and Icons ==
In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.
As we have seen so far, blocks use two properties of [[Blocks_Howto#variable_content| $this->content]]<nowiki>: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.</nowiki>
Instead, Moodle expects such blocks to set two other properties when the [[Blocks_Howto#method_get_content| get_content]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size.
In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

class block_my_menu extends block_list {
// The init() method does not need to change at all
}
In addition to making this change, we must of course also modify the [[Blocks_Howto#method_get_content| get_content]] method to construct the [[Blocks_Howto#variable_content| $this->content]] variable as discussed above:

function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" class="icon" alt="" />';

// Add more list items here

return $this->content;
}
To summarize, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks_Howto#method_get_content| get_content]] method. Adding the mandatory [[Blocks_Howto#method_init| init]] method as discussed earlier will then give us our first list block in no time!

== Appendix A: Reference ==

This Appendix will discuss the base class '''block_base''' from which all other block classes derive, and present each and every method that can be overridden by block developers in detail. Methods that should '''not''' be overridden are explicitly referred to as such. After reading this Appendix, you will have a clear understanding of every method which you should or could override to implement functionality for your block.

The methods are divided into three categories: those you may use and override in your block, those that you may '''not''' override but might want to use, and those internal methods that should '''neither''' be used '''nor''' overridden. In each category, methods are presented in alphabetical order.

=== Methods you can freely use and override: ===
** <div class="function_title">after_install</div>
<nowiki>
function after_install() {
}
</nowiki>
Available in Moodle 1.7 and later

This method is designed to be overridden by block subclasses, and allows you to specify a set of tasks to be executed after the block is installed. For example, you may wish to store the date on which the block was installed. However, each database type has its own way of getting the current date, and when using XMLDB to install your block, these operations are also unsupported. So the best way to complete such a task while maintaining database abstraction is to use XMLDB to install the block, and then use the after_install() method to perform the insertion before the block is used.

Please note that after_install() is called once per block, not once per instance.

** <div class="function_title">applicable_formats</div>
<nowiki>
function applicable_formats() {
// Default case: the block can be used in courses and site index, but not in activities
return array('all' => true, 'mod' => false);
}
</nowiki>
Available in Moodle 1.5 and later

This method allows you to control which pages your block can be added to. Page formats are formulated from the full path of the script that is used to display that page. You should return an array with the keys being page format names and the values being booleans (true or false). Your block is only allowed to appear in those formats where the value is true.
Example format names are: '''course-view''', '''site-index''' (this is an exception, referring front page of the Moodle site), '''course-format-weeks''' (referring to a specific course format), '''mod-quiz''' (referring to the quiz module) and '''all''' (this will be used for those formats you have not explicitly allowed or disallowed).
The full matching rules are:
*** Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
*** The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
*** The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
*** The order that the format names appear does not make any difference.

** <div class="function_title">before_delete</div>

<nowiki>
function before_delete() {
}
</nowiki>
Available in Moodle 1.7 and later

This method is called when an administrator removes a block from the Moodle installation, immediately before the relevant database tables are deleted. It allows block authors to perform any necessary cleanup - removing temporary files and so on - before the block is deleted.

** <div class="function_title">config_print</div>
<nowiki>
function config_print() {
// Default behavior: print the config_global.html file
// You don't need to override this if you're satisfied with the above
if (!$this->has_config()) {
return false;
}
global $CFG, $THEME;
print_simple_box_start('center', '', $THEME->cellheading);
include($CFG->dirroot.'/blocks/'. $this->name() .'/config_global.html');
print_simple_box_end();
return true;
}</nowiki>
Available in Moodle 1.5 and later

This method allows you to choose how to display the global configuration screen for your block. This is the screen that the administrator is presented with when he chooses "Settings..." for a specific block. Override it if you need something much more complex than the default implementation allows you to do. However, keep these points in mind:
**# If you save your configuration options in $CFG, you will probably need to use global $CFG; before including any HTML configuration screens.
**# The HTML <input> elements that you include in your method's output will be automatically enclosed in a <form> element. You do not need to worry about where and how that form is submitted; however, you '''must''' provide a way to submit it (i.e., an <input type="submit" />.
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">config_save</div>

function config_save($data) {
// Default behavior: save all variables as $CFG properties
// You don't need to override this if you 're satisfied with the above
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
Available in Moodle 1.5 and later

This method allows you to override the storage mechanism for your global configuration data. The received argument is an associative array, with the keys being setting names and the values being setting values. The default implementation saves everything as Moodle $CFG variables.
Note that $data does not hold all of the submitted POST data because Moodle adds some hidden fields to the form in order to be able to process it. However, before calling this method it strips the hidden fields from the received data and so when this method is called only the "real" configuration data remain.
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">get_content</div>

function get_content() {
// This should be implemented by the derived class.
return NULL;
}
Available in Moodle 1.5 and later

This method should, when called, populate the [[Blocks_Howto#variable_content| $this->content]] variable of your block. Populating the variable means:
'''EITHER'''<br />defining $this->content->text and $this->content->footer if your block derives from '''block_base'''. Both of these should be strings, and can contain arbitrary HTML.
'''OR'''<br />defining $this->content->items, $this->content->icons and $this->content->footer if your block derives from '''block_list'''. The first two should be numerically indexed arrays having the exact same number of elements. $this->content->items is an array of strings that can contain arbitrary HTML while $this->content->icons also contains should strings, but those must be fully-qualified HTML <img> tags '''and nothing else'''. $this->content->footer is a string, as above.
If you set ''all'' of these variables to their default "empty" values (empty arrays for the arrays and empty strings for the strings), the block will '''not''' be displayed at all except to editing users. This is a good way of having your block hide itself to unclutter the screen if there is no reason to have it displayed.
Before starting to populate [[Blocks_Howto#variable_content| $this->content]], you should also include a simple caching check. If [[Blocks_Howto#variable_content| $this->content]] is exactly equal to NULL then proceed as normally, while if it is not, return the existing value instead of calculating it once more. If you fail to do this, Moodle will suffer a performance hit.
In any case, your method should return the fully constructed [[Blocks_Howto#variable_content| $this->content]] variable.
** <div class="function_title">has_config</div>

function has_config() {
return false;
}
Available in Moodle 1.5 and later

This method should return a boolean value that denotes whether your block wants to present a configuration interface to site admins or not. The configuration that this interface offers will impact all instances of the block equally.
To actually implement the configuration interface, you will either need to rely on the default [[Blocks_Howto#method_instance_config_print| config_print]] method or override it. The full guide contains [[Blocks_Howto#section_effects_of_globalization| more information on this]].
** <div class="function_title">hide_header</div>

function hide_header() {
//Default, false--> the header is shown
return false;
}
Available in Moodle 1.5 and later

This method should return a boolean value that denotes whether your block wants to hide its header (or title). Thus, if you override it to return true, your block will not display a title unless the current user is in editing mode.
** <div class="function_title">html_attributes</div>

function html_attributes() {
// Default case: an id with the instance and a class with our name in it
return array('id' => 'inst'.$this->instance->id, 'class' => 'block_'. $this->name());
}
Available in Moodle 1.5 and later

This method should return an associative array of HTML attributes that will be given to your block's container element when Moodle constructs the output HTML. No sanitization will be performed in these elements at all.
If you intend to override this method, you should return the default attributes as well as those you add yourself. The recommended way to do this is:

function html_attributes() {
$attrs = parent::html_attributes();
// Add your own attributes here, e.g.
// $attrs['width'] = '50%';
return $attrs;
}
** <div class="function_title">init</div>

function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
Available in Moodle 1.5 and later

This method must be implemented for all blocks. It has to assign meaningful values to the object variables [[Blocks_Howto#variable_title| $this->title]] and [[Blocks_Howto#variable_version| $this->version]] (which is used by Moodle for performing automatic updates when available).
No return value is expected from this method.
** <div class="function_title">instance_allow_config</div>

function instance_allow_config() {
return false;
}
Available in Moodle 1.5 and later

This method should return a boolean value. True indicates that your block wants to have per-instance configuration, while false means it does not. If you do want to implement instance configuration, you will need to take some additional steps apart from overriding this method; refer to the full guide for [[Blocks_Howto#section_configure_that_out| more information]].
This method's return value is irrelevant if [[Blocks_Howto#method_instance_allow_multiple| instance_allow_multiple]] returns true; it is assumed that if you want multiple instances then each instance needs its own configuration.
** <div class="function_title">instance_allow_multiple</div>

function instance_allow_multiple() {
// Are you going to allow multiple instances of each block?
// If yes, then it is assumed that the block WILL USE per-instance configuration
return false;
}
Available in Moodle 1.5 and later

This method should return a boolean value, indicating whether you want to allow multiple instances of this block in the same page or not. If you do allow multiple instances, it is assumed that you will also be providing per-instance configuration for the block. Thus, you will need to take some additional steps apart from overriding this method; refer to the full guide for [[Blocks_Howto#section_configure_that_out| more information]].
** <div class="function_title">instance_config_print</div>
<nowiki>
function instance_config_print() {
// Default behavior: print the config_instance.html file
// You don't need to override this if you're satisfied with the above
if (!$this->instance_allow_multiple() && !$this->instance_allow_config()) {
return false;
}
global $CFG, $THEME;

if (is_file($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html')) {
print_simple_box_start('center', '', $THEME->cellheading);
include($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html');
print_simple_box_end();
} else {
notice(get_string('blockconfigbad'),
str_replace('blockaction=', 'dummy=', qualified_me()));
}

return true;
}</nowiki>
Available in Moodle 1.5 and later

This method allows you to choose how to display the instance configuration screen for your block. Override it if you need something much more complex than the default implementation allows you to do. Keep in mind that whatever you do output from [[Blocks_Howto#method_instance_config_print| config_print]], it will be enclosed in a HTML form automatically. You only need to provide a way to submit that form.
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">instance_config_save</div>

function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance', 'configdata', base64_encode(serialize($data)),
'id', $this->instance->id);
}
Available in Moodle 1.5 and later

This method allows you to override the storage mechanism for your instance configuration data. The received argument is an associative array, with the keys being setting names and the values being setting values.
The configuration must be stored in the "configdata" field of your instance record in the database so that Moodle can auto-load it when your block is constructed. However, you may still want to override this method if you need to take some additional action apart from saving the data. In that case, you really should do what data processing you want and then call parent::instance_config_save($data) with your new $data array. This will keep your block from becoming broken if the default implementation of instance_config_save changes in the future.
Note that $data does not hold all of the submitted POST data because Moodle adds some hidden fields to the form in order to be able to process it. However, before calling this method it strips the hidden fields from the received data and so when this method is called only the "real" configuration data remain.
If you want to update the stored copy of the configuration data at run time (for example to persist some changes you made programmatically), you should not use this method. The correct procedure for that purpose is to call [[Blocks_Howto#method_instance_config_commit| instance_config_commit]].
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">preferred_width</div>

function preferred_width() {
// Default case: the block wants to be 180 pixels wide
return 180;
}
Available in Moodle 1.5 and later

This method should return an integer value, which is the number of pixels of width your block wants to take up when displayed. Moodle will try to honor your request, but this is actually up to the implementation of the format of the page your block is being displayed in and therefore no guarantee is given. You might get exactly what you want or any other width the format decides to give you, although obviously an effort to accomodate your block will be made.
Most display logic at this point allocates the maximum width requested by the blocks that are going to be displayed, bounding it both downwards and upwards to avoid having a bad-behaving block break the format.
** <div class="function_title">refresh_content</div>

function refresh_content() {
// Nothing special here, depends on content()
$this->content = NULL;
return $this->get_content();
}
Available in Moodle 1.5 and later

This method should cause your block to recalculate its content immediately. If you follow the guidelines for [[Blocks_Howto#get_content| get_content]], which say to respect the current content value unless it is NULL, then the default implementation will do the job just fine.
You should return the new value of [[Blocks_Howto#variable_content| $this->content]] after refreshing it.
** <div class="function_title">specialization</div>

function specialization() {
// Just to make sure that this method exists.
}
Available in Moodle 1.5 and later

This method is automatically called by the framework immediately after your instance data (which includes the page type and id and all instance configuration data) is loaded from the database. If there is some action that you need to take as soon as this data becomes available and which cannot be taken earlier, you should override this method.
The instance data will be available in the variables [[Blocks_Howto#variable_instance| $this->instance]] and [[Blocks_Howto#variable_config| $this->config]].
This method should not return anything at all.
=== Methods which you should ''not'' override but may want to use: ===
** <div class="function_title">instance_config_commit</div>

function instance_config_commit() {
return set_field('block_instance',
'configdata', base64_encode(serialize($this->config)),
'id', $this->instance->id);
}
Available in Moodle 1.5 and later

This method saves the current contents of [[Blocks_Howto#variable_config| $this->config]] to the database. If you need to make a change to the configuration settings of a block instance at run time (and not through the usual avenue of letting the user change it), just make the changes you want to [[Blocks_Howto#variable_config| $this->config]] and then call this method.
** <div class="function_title">get_content_type</div>

function get_content_type() {
return $this->content_type;
}
Available in Moodle 1.5 and later

This method returns the value of [[Blocks_Howto#variable_content_type| $this->content_type]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
** <div class="function_title">get_title</div>

function get_title() {
return $this->title;
}
Available in Moodle 1.5 and later

This method returns the value of [[Blocks_Howto#variable_title| $this->title]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
** <div class="function_title">get_version</div>

function get_version() {
return $this->version;
}
Available in Moodle 1.5 and later

This method returns the value of [[Blocks_Howto#variable_version| $this->version]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
** <div class="function_title">is_empty</div>
For blocks that extend class '''block_base'''<nowiki>:</nowiki>

function is_empty() {
$this->get_content();
return(empty($this->content->text) && empty($this->content->footer));
}
Available in Moodle 1.5 and later

For blocks that extend class '''block_list'''<nowiki>:</nowiki>

function is_empty() {
$this->get_content();
return (empty($this->content->items) && empty($this->content->footer));
}
This method returns the a boolean true/false value, depending on whether the block has any content at all to display. Blocks without content are not displayed by the framework.
** <div class="function_title">name</div>

function name() {
static $myname;
if ($myname === NULL) {
$myname = strtolower(get_class($this));
$myname = substr($myname, strpos($myname, '_') + 1);
}
return $myname;
}
Available in Moodle 1.5 and later

This method returns the internal name of your block inside Moodle, without the '''block_''' prefix. Obtaining the name of a block object is sometimes useful because it can be used to write code that is agnostic to the actual block's name (and thus more generic and reusable). For an example of this technique, see the [[Blocks_Howto#method_config_print| config_print]] method.
=== Methods which you should ''not'' override and ''not'' use at all: ===
** <div class="function_title">_self_test</div>
This is a private method; no description is given.
** <div class="function_title">_add_edit_controls</div>
This is a private method; no description is given.
** <div class="function_title">_load_instance</div>
This is a private method; no description is given.
** <div class="function_title">_print_block</div>
This is a private method; no description is given.
** <div class="function_title">_print_shadow</div>
This is a private method; no description is given.

The class '''block_base''' also has a few standard member variables which its methods manipulate. These variables, the purpose of each and the type of data they are expected to hold is explained in the next section of this Appendix.

=== Class variables: ===

* <div class="variable_title">$this->config</div>
This variable holds all the specialized instance configuration data that have been provided for this specific block instance (object). It is an object of type stdClass, with member variables directly corresponding to the HTML <input> elements in the block's <span class="filename">config_instance.html</span> file.
The variable is initialized just after the block object is constructed, immediately before [[Blocks_Howto#method_specialization| specialization]] is called for the object. It is possible that the block has no instance configuration, in which case the variable will be NULL.
It is obvious that there is a direct relationship between this variable and the configdata field in the mdl_block_instance table. However, it is ''strongly'' advised that you refrain from accessing the configdata field yourself. If you absolutely must update its value at any time, it is recommended that you call the method [[Blocks_Howto#method_instance_config_commit| instance_config_commit]] to do the actual work.
* <div class="variable_title">$this->content_type</div>
This variable instructs Moodle on what type of content it should assume the block has, and is used to differentiate text blocks from list blocks. It is essential that it has a meaningful value, as Moodle depends on this for correctly displaying the block on screen. Consequently, this variable is closely tied with the variable [[Blocks_Howto#variable_content| $this->content]]. The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each block.
The only valid values for this variable are the two named constants [[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]] and [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]].
* <div class="variable_title">$this->content</div>
This variable holds all the actual content that is displayed inside each block. Valid values for it are either NULL or an object of class stdClass, which must have specific member variables set as explained below. Normally, it begins life with a value of NULL and it becomes fully constructed (i.e., an object) when [[Blocks_Howto#method_get_content| get_content]] is called.
After it is fully constructed, this object is expected to have certain properties, depending on the value of [[Blocks_Howto#variable_content_type| $this->content_type]]. Specifically:
** If [[Blocks_Howto#variable_content_type| $this->content_type]] is [[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]], then [[Blocks_Howto#variable_content| $this->content]] is expected to have the following member variables:
*** <div>'''text'''</div>This is a string of arbitrary length and content. It is displayed inside the main area of the block, and can contain HTML.
*** <div>'''footer'''</div>This is a string of arbitrary length and contents. It is displayed below the text, using a smaller font size. It can also contain HTML.
** If [[Blocks_Howto#variable_content_type| $this->content_type]] is [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]], then [[Blocks_Howto#variable_content| $this->content]] is expected to have the following member variables:
*** <div>'''items'''</div>This is a numerically indexed array of strings which holds the title for each item in the list that will be displayed in the block's area. Since usually such lists function like menus, the title for each item is normally a fully qualified HTML <a> tag.
*** <div>'''icons'''</div>This is a numerically indexed array of strings which represent the images displayed before each item of the list. It therefore follows that it should have the exact number of elements as the items member variable. Each item in this array should be a fully qualified HTML <img> tag.
*** <div>'''footer'''</div>This is a string of arbitrary length and contents. It is displayed below the text, using a smaller font size. It can also contain HTML.
* <div class="variable_title">$this->instance</div>
This member variable holds all the specific information that differentiates one block instance (i.e., the PHP object that embodies it) from another. It is an object of type stdClass retrieved by calling get_record on the table mdl_block_instance. Its member variables, then, directly correspond to the fields of that table. It is initialized immediately after the block object itself is constructed.
* <div class="variable_title">$this->title</div>
This variable is a string that contains the human-readable name of the block. It is used to refer to blocks of that type throughout Moodle, for example in the administrator's block configuration screen and in the editing teacher's add block menu. It is also the title that is printed when the block is displayed on screen, although blocks can specifically change this title to something else if they wish (see below). The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each object.
In the case of blocks which may want to configure their title dynamically through instance configuration, it is still essential to provide a valid title inside [[Blocks_Howto#method_init| init]]. This title may then be overridden when the [[Blocks_Howto#method_specialization| specialization]] method is called by the framework:

function specialization() {
// At this point, $this->instance and $this->config are available
// for use. We can now change the title to whatever we want.
$this->title = $this->config->variable_holding_the_title;
}

A lot of blocks seem to use

$this->title = get_string('blockname', ... );

to set the title of the block (and then put a more specific title inside the language file)
If there is no proper language string, the title of the block will then be set to ''blockname''. If there is another block with the same generic title, then an error will show up: Naming conflict.

To avoid this error on installations with missing language strings, use a more specific name when calling the language string...

$this->title = get_string('simplehtml', ... );

That way all blocks will show up with a unique title in the admin area, even if people have not yet succeeded in placing language files in the correct location

* <div class="variable_title">$this->version</div>
This variable should hold each block's version number in the form '''YYYYMMDDXX''', as per the convention throughout Moodle. The version number is used by Moodle to detect when a block has been upgraded and it consequently needs to run the block's upgrade code to bring the "old" version of the block's data up to date. The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each block.
Most blocks do not keep complex data of their own in the database the way that modules do, so in most cases nothing actually happens during a block version upgrade. However, the version number is displayed in the administration interface for blocks. It is good practice therefore to change your block's version number when it gains new functionality or receives important bug fixes, to enable site administrators to easily identify the exact version of the block they are working with.

Appearing throughout the code related to the Blocks API, there is a number of predefined constants that are utilized to avoid the use of "magic numbers" in the code. These constants are:

=== Named constants: ===

* <div class="named_constant">BLOCK_TYPE_LIST</div>
This is one of the two valid values for the [[Blocks_Howto#variable_content_type| $this->content_type]] member variable of every block. Its value specifies the exact requirements that Moodle will then have for [[Blocks_Howto#variable_content| $this->content]].
* <div class="named_constant">BLOCK_TYPE_TEXT</div>
This is one of the two valid values for the [[Blocks_Howto#variable_content_type| $this->content_type]] member variable of every block. Its value specifies the exact requirements that Moodle will then have for [[Blocks_Howto#variable_content| $this->content]].

== Appendix B: Differences in the Blocks API for Moodle versions prior to 1.5 ==

This Appendix will discuss what changes in the Blocks API were introduced by Moodle 1.5 and what steps developers need to take to update their blocks to be fully compatible with Moodle 1.5. Unfortunately, with these changes backward compatibility is broken; this means that blocks from Moodle 1.4 will never work with 1.5 and vice versa.

=== Class naming conventions changed ===
In Moodle 1.4, all block classes were required to have a name like '''CourseBlock_something''' and the base class from which the derived was '''MoodleBlock'''. This has changed in Moodle 1.5, to bring the naming conventions in line with other object-oriented aspects of Moodle (for example there are classes enrolment_base, resource_base etc). The new block classes should instead be named like '''block_something''' and derive from '''block_base'''. This means that in order to make a block compatible with Moodle 1.5, you need to change the class definition

class CourseBlock_online_users extends MoodleBlock { ... }
to

class block_online_users extends block_base { ... }
An exception to the above is the special case where the block is intended to display a list of items instead of arbitrary text; in this case the block class must derive from class '''block_list''' instead, like this:

class block_admin extends block_list { ... }

=== Constructor versus init() ===

In Moodle 1.4, in each block class it was mandatory to define a constructor which accepted a course data record as an argument (the example is from the actual Online Users block):

function CourseBlock_online_users ($course) {
$this->title = get_string('blockname','block_online_users');
$this->content_type = BLOCK_TYPE_TEXT;
$this->course = $course;
$this->version = 2004052700;
}
In contrast, Moodle 1.5 does away with the constructor and instead requires you to define an init() method that takes no arguments:

function init() {
$this->title = get_string('blockname','block_online_users');
$this->version = 2004111600;
}
Of course, this leaves you without access to the $course object, which you might actually need. Since that's probably going to be needed inside [[Blocks_Howto#method_get_content| get_content]], the way to retrieve it is by using this code:

$course = get_record('course', 'id', $this->instance->pageid);
If you are going to need access to $course from inside other methods in addition to [[Blocks_Howto#method_get_content| get_content]], you might fetch the $course object inside the [[Blocks_Howto#method_specialization| specialization]] method and save it as a class variable for later use, in order to avoid executing the same query multiple times:

function specialization() {
$this->course = get_record('course', 'id', $this->instance->pageid);
}

=== Blocks with configuration ===
In Moodle 1.4, blocks could only have what are now (in Moodle 1.5) called "global configuration" options, to differentiate from the new "instance configuration" options. If your block has support for configuration, you will need to take these steps:
## Rename your <span class="filename">config.html</span> file to <span class="filename">config_global.html</span>.
## Edit the newly renamed file and completely remove the <form> tag (Moodle now wraps your configuration in a form automatically).
## If you are using any HTML <input> tags other than those that directly affect your configuration (for example, "sesskey"), REMOVE those too (Moodle will add them automatically as required).
## If you have overridden '''print_config''', rename your method to '''config_print'''.
## If you have overridden '''handle_config''', rename your method to '''config_save'''.
=== Blocks with customized applicable formats ===
The correct way to specify the formats you want to allow or disallow your block to exist has been reworked for Moodle 1.5 to take account of the fact that blocks are no longer restricted to just courses. To have a block retain its intended behavior, you must change these format names (array keys in the return value of [[Blocks_Howto#method_applicable_formats| applicable_formats]]) if they are used in your block:
#* '''social''' should become '''course-view-social'''
#* '''topics''' should become '''course-view-topics'''
#* '''weeks''' should become '''course-view-weeks'''
You should also keep in mind that there is now the possibility of blocks being displayed in other pages too, like the introductory page that users see when they enter an activity module. You might therefore need to make the specification for applicable formats more restrictive to keep your block out of pages it is not supposed to be shown in. Also, there are subtle changes to the way that the final decision to allow or disallow a block is made. For the technical details refer to the definition of [[Blocks_Howto#method_applicable_formats| applicable_formats]], and for a more extended example read [[Blocks_Howto#section_authorized_personnel_only| the section dedicated to this subject]].
That's everything; your block will now be ready for use in Moodle 1.5!

[[Category:Developer|Blocks]]

[[es:Desarrollo de bloques]]

== Creating Database Tables for Blocks ==

'''The following describes what to do in Moodle <= 1.6. For Moodle >= 1.7, you need to use [[Development:XMLDB_Documentation|XMLDB]], that is, create an install.xml file, instead of *.sql files.'''

You can easily create a database table for your block by adding
two files mysql.sql and postgres7.sql to a subdirectory db/ of
your block. The tables HAVE TO be named the same way as the
block (e.g. block_rss2_feeds) otherwise moodle will not be able
to drop the table upon removal of the block from the system.
Here is an example for mysql.sql:

CREATE TABLE prefix_rss2_feeds (
`id` int(11) NOT NULL auto_increment,
`userid` int(11) NOT NULL default '0',
`title` text NOT NULL default '',
`description` text NOT NULL default '',
`url` varchar(255) NOT NULL default '',
`pingbacktokenurl` varchar(255) NOT NULL default '',
PRIMARY KEY (`id`)
) TYPE=MyISAM COMMENT='Remote news feed information.';

Pay attention that, furthermore, you might want to add a
mysql.php and postgres7.php page that contains update
routines for upgrading the database tables with evolving
version numbers of the block. In case you use that be sure
that you provide the necessary structure (again function
name should be like the block name + "_upgrade"!).
Here is an example:

function rss_pingback_upgrade( $oldversion ) {
global $CFG;
if ($oldversion < 2003111500) {
# Do something ...
}
return true;
}

Grader report

2008-09-10T21:48:57Z

Davidkazuhiro: /* Basics */ not =>note

{{Grades}}The grader report page is the main teacher view of the new gradebook in Moodle 1.9. For versions prior to 1.9, look [[Grades_pre-1.9 | here]].

=Basics=
The gradebook collects [[Grade_items|items]] that have been graded from the various parts of Moodle that are assessed, and allows you to view and change them as well as sort them out into [[Grade_categories|categories]] and calculate totals in various ways. When you add an assessed item in a Moodle course, the gradebook automatically creates space for the grades it will produce and also adds the grades themselves as they are generated, either by the system or by you.

The [[Grades|grades]] displayed are initially displayed as the raw marks from the assessments themselves, so will depend on how you set those up e.g. an essay out of 36 will appear as how ever many raw marks that student got, not a percentage (although this can be changed later, see below).

Note that various default options for the gradebook are set at system level by the administrator and can be marked as being overridable by you, or fixed. This means that the options will not always be set up the same way for every user when they see the grader report for the first time.

=Display=
==Layout==
[[Image:gradebook_normal_mode.png|right|thumb|Grader report in non-editing mode]]
Along the top are several rows: first the course, then the category, then the actual column (e.g. an essay or a category total). When you start off, every essay, quiz etc is in the '''uncategorised''' category, which is named after the course by default, but can be changed if needed.

You can add a row showing the range of possible scores by going to [[Grade_preferences|My report preferences]] and selecting '''Show ranges'''.

There are three ways that the categories can be displayed

* Grades only - without the category totals column
* Collapsed - Category total column only
* Full view - grades and the aggregates (the totals column for the category)

Each section has a small icon immediately to the right of its name. Clicking this will cycle through these display modes for that category. + goes to grades only view, o goes to full view and - goes to collapsed view.

===Other layout options===
The defaults for these options can be set at site level by going to Administration->Grades->[[Gradebook_report_settings|Report settings]]->Grader report.

*You can add a row showing the range of possible scores by going to [[Grade_preferences|My report preferences]] and selecting '''Show ranges'''.

==Highlighting rows and columns==
When your gradebook starts to grow, it can be hard to keep track of which student and which assignment a cell refers to. Highlighting solves that.
* Clicking on empty space in the cell that contains the students name will toggle the highlighting of that entire row
* Clicking on empty space in the cell at the top of each column will toggle highlighting of the entire column
(Note: this requires Javascript to be enabled in your browser.)

==Highlighting scores that are either adequate or unacceptable in red and green==
Turn editing on and click on the edit icon in the controls cell at the top of the column. You can then (maybe need to click 'show advanced') see the option to enter a 'grade to pass'. Once set, any grades falling above this will be highlighted in green and any below will be highlighted in red.

==Categorising the grades==
The 'Choose an action...' drop down on the upper left will let you switch to other views
* '''Edit categories and items''' will allow you to set up your assessments in different categories e.g. 'classwork', 'homework' etc.

Each category will then have its own '''Category total''' column.

=Editing=
[[Image:gradebook_edit_mode.png|right|thumb|Grader report in editing mode]]
Note: Editing anything in the gradebook refers to editing the grades '''only''' and none of the available operations bear any relationship to editing the main course page i.e. the appearance of your course page cannot be influenced by anything you do in the gradebook. The "Turn editing on" button functions separately to the main course one, so editing can be on in the gradebook, but simultaneously off when you switch back to course view. This is because editing grades and editing the course page are separate capabilities and a role e.g. 'non-editing teacher' may only have one or the other.

==Altering the grades==
You can click "Turn editing on" at the top right to show an edit icon next to each grade. Clicking on the icon will bring up the editing screen for that grade which will allow you to set the grade, its written feedback and a number of other attributes.

Alternatively, you can click on "[[Grade_preferences|My report preferences]]"' and choose "Quick grading" and "Quick feedback" to make the report appear with editable boxes containing each grade, so you can change many at once.

Quick feedback is switched off by default, but you can easily switch it on or off using the "Show Quick Feedback" link above the grader report, when editing is on. Alternatively you can switch it on and off in the page "[[Grade_preferences|My report preferences]]".

==Calculating totals==
Rather than a simple average or sum, Moodle can perform very complex calculations to produce the totals for each category and for the whole course. e.g. you want to take an average of 3 items from one category, double it, then add it to the average of another category.

You can do this using calculations. Either turn on editing, then click '''Show calculations''', or go to '''[[Grade_preferences|My report preferences]]''', choose '''show calculations''', then save and turn editing on. You will then see a small calculator icon next to each total column which, when you click on it, will take you to the page [[Edit grade calculation]] where there are instructions.

To choose how the grades are aggregated for the totals within categories, you can turn editing on and click on the little editing icon for the category. You can then choose to have means, medians, modes etc. leave out empty grades and other settings.

==Hiding columns or individual grades==
Turning on editing then clicking the "Show show/hide icons" link will give you the familiar show/hide eye icon next to each grade and at the top of each column. For more information, read about [[Grade_hiding|grade hiding]].

==Recalculating==
If you change any part of an assesment e.g. alter the maximum grade for one of the questions in a quiz, you may find that the columns do not yet reflect the change you have made. Click 'Turn editing on' twice to force the gradebook to re-check.

==See also==
*[[Edit grade calculation]]
*[[Grade preferences]]
*[http://www.youtube.com/watch?v=EB58W3KePBc Video showing the basic gradebook setup and use]
*[http://www.youtube.com/watch?v=jWPUEqdhI4A Video showing how to change the display of grades in the gradebook]
*[http://www.youtube.com/watch?v=5hrLNbifiGQ Video explaining the different gradebook reports]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=87844 What happens in the 1.9 gradebook when students are unenrolled from a course] forum discussion

[[ca:grade/report/grader/index]]
[[fr:Rapport de l'évaluateur]]

XMLDB introduction

2008-08-06T22:47:31Z

Davidkazuhiro: a facelift for the article

[[Development:XMLDB Documentation|XMLDB Documentation]] > Introduction
----
__NOTOC__
One of the main upcoming features in Moodle 1.7 will be its ability to work with some more [[wikipedia:RDBMS|RDBMS]] ([[wikipedia:MSSQL|MSSQL]] and [[wikipedia:Oracle database|Oracle]]) while maintaining everything working properly with both [[MySQL]] and [[PostgreSQL]]. As Moodle core uses [http://adodb.sourceforge.net/ ADOdb] internally, this possibility has been present since the beginning and, with the current maturity of the project (5 years old baby!), this can be a good moment to sort all this out.

Initially, all our tests and preliminary work was to inspect how [http://adodb.sourceforge.net/ ADOdb] was doing its work, and how we could mix together all those 4 RDBMS, whose SQL dialects, although pretty similar, have some differences and idiosyncrasies that force us to do some important changes to our current database code (formerly '''datalib.php''') and how it's used by the rest of Moodle.

All the changes to be performed, which primary objective is to enable Moodle to work with more RDBMS, must be fulfilled by following these non-functional requirements:

* '''Provide one layer (new) for DB creation/upgrade''' ([[wikipedia:Data_Definition_Language|DDL]]): With this, developers will create their structures in one neutral form, independent of the exact implementation to be used by each RDBMS.

* '''Provide one layer (existing) for DB handling''' ([[wikipedia:Data_Manipulation_Language|DML]]): With this, developers will request/store information also in one neutral form, independent of the RDBMS being used.

* '''Easy migration path from previous versions''': The current installation/upgrade system will work until, at least, Moodle 2.0, allowing 3rd party developers to migrate to the new system.

* '''Simple, usable and effective''': Until now, the way to upgrade Moodle has been really cool and it has worked pretty fine since the beginning. However, it has forced developers to maintain at least two installation and two upgrade scripts for each module/plugin. The new alternative will have only one file to install and one file to upgrade (per module/plugin too), reducing the possibility of mistakes drastically.

* '''Conditional code usage must be minimised''': Database libraries must accept 99% of potential SQL sentences, building/transforming them as necessary to work properly under any RDBMS. The number of places using custom (per DB) code should be minimum.

* '''Well documented''': All the functions defined, both at DML and DDL level must be well documented, helping the developer to find and use the correct one in each situation.

== The Stack ==

The next stack shows how Moodle 1.7 code will interact with the underlying RDBMS. It will help us understand a bit more what we are trying to do and will explain some of the points related in the Roadmap (below in this page).

[[Image:MoodleDBStack.png|center]]

Moodle code will use two ''languages'' to perform its DB actions:

* '''XMLDB neutral description files''': To create, modify and delete database objects (DDL: create/alter/drop tables, fields, indexes, constraints...). It consists of a collection of validated, standard, XML files. They will be used to define all the DB objects. New for 1.7.
* '''Moodle SQL neutral statements''': To add, modify, delete and select database information (DML: insert/update/delete/select records). To modify for 1.7.

Please note the '''neutral''' keyword used in the expressions above. It means that both '''languages''' will be 100% the same, independent of the underlying RDBMS being used. And this must be particularly true for the XMLDB part.

Obviously it's possible that in the SQL part we found some specialised queries (using complex joins, regular expressions...) that will force us to do some '''Exceptions'''. Well, they can exist (in fact, they exist), but we always must try to provide an alternate path to minimise them using neutral statements and standard libraries.

Each one of the '''languages''' above will use its own library to do the work:

* '''Moodle DDL Library''' ([[Development:DDL functions|ddllib.php]]): Where all the functions needed to handle DB objects will exist. This library is new for 1.7 and will provide developers with an high level of abstraction. As input it will accept some well defined objects and actions and it will execute the proper commands for the RDBMS being used.
* '''Moodle DML Library''' ([[Development:DML functions|dmllib.php]]): Where all the functions needed to handle DB contents will exist. This library is new for 1.7, although its contents are, basically, functions currently present in '''datalib.php''' (moved from there). All those DML functions will offer cross-db support for insert/update/delete/select statements using a common behaviour.

Also note that '''datalib.php''' is still present in the schema above. It will contain all the functions that haven't been moved to the new '''ddllib.php''' and '''dmllib.php''' libraries. Only some common functions will remain there, and these will disappear (it's considered a legacy library) in upcoming '''Moodle''' releases (after 1.7) by moving all those functions to their proper library (course/lib.php, user/lib.php....).

Both of these libraries (plus the small '''Exceptions''' bar) will perform all their actions using the '''ADOdb Database Abstraction Library for PHP''' that will receive all the requests from them, communicate with the DB ('''MySQL''', '''PostgreSQL''', '''Oracle''' or '''SQL*Server'''), retrieve results and forward them back to originator library.

== The process ==

This section points to the main areas of information about the '''process of design and implementation''' of the new XMLDB layer:

* [[XMLDB Roadmap|Roadmap]]: Where the whole process is defined. It has been split into small chunks to be performed and tested easily. Also, such documents should be used to track what's done and what's pending, while using easy nomenclature.

* [[XMLDB Problems|Problems]]: A comprehensive list of issues that need to be determined/solved prior to incorporating them into the [[XMLDB Roadmap|roadmap]].

== The documentation ==

This section points to the '''main documentation index''' about the implemented XMLDB:

* [[Development:XMLDB Documentation|Documentation]]: Where you'll find quick links to different parts of the XMLDB documentation.

==See also==

=== XMLDB related ===

* [[Development:XMLDB preliminary links|XMLDB preliminary links]] - A collection of links about general info, searched and analysed at the initial stages of the project
* [[Development:XMLDB preliminary notes|XMLDB preliminary notes]] - A collection of notes collected in the early stages of this project, pointing both to some changes required and some problems to solve.

=== Database related ===

* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

[[Category:XMLDB]]

[[zh:开发:XML数据库计划]]

XMLDB introduction

2008-08-06T21:49:27Z

Davidkazuhiro: trying to make the sentence make more sense

[[Development:XMLDB Documentation|XMLDB Documentation]] > Introduction
----
__NOTOC__
One of the main upcoming features in Moodle 1.7 will be its ability to work with some more [[wikipedia:RDBMS|RDBMS]] ([[wikipedia:MSSQL|MSSQL]] and [[wikipedia:Oracle database|Oracle]]) while maintaining everything working properly with both [[MySQL]] and [[PostgreSQL]]. As Moodle core uses [http://adodb.sourceforge.net/ ADOdb] internally, this possibility has been present since the beginning and, with the current maturity of the project (5 years old baby!), this can be a good moment to sort all this out.

Initially, all our tests and preliminary work was to inspect how [http://adodb.sourceforge.net/ ADOdb] was doing its work, and how we could mix together all those 4 RDBMS, whose SQL dialects, although pretty similar, have some differences and idiosyncrasies that force us to do some important changes to our current database code (formerly '''datalib.php''') and how it's used by the rest of Moodle.

All the changes to be performed, which primary objective is to enable Moodle to work with more RDBMS, must be fulfilled by following these non-functional requirements:

* '''Provide one layer (new) for DB creation/upgrade''' ([[wikipedia:Data_Definition_Language|DDL]]): With this, developers will create their structures in one neutral form, independent of the exact implementation to be used by each RDBMS.

* '''Provide one layer (existing) for DB handling''' ([[wikipedia:Data_Manipulation_Language|DML]]): With this, developers will request/store information also in one neutral form, independent of the RDBMS being used.

* '''Easy migration path from previous versions''': The current installation/upgrade system will work until, at least, Moodle 2.0, allowing 3rd part developers to migrate along the time to the new system.

* '''Simple, usable and effective''': Until now, the way to upgrade Moodle has been really cool and it has worked pretty fine since the beginning, but it has forced developers to maintain at least two installation and two upgrade scripts for each module/plugin. The new alternative will have only one file to install and one file to upgrade (per module/plugin too), reducing the possibility of mistakes in an high degree.

* '''Conditional code usage must be minimised''': Database libraries must accept 99% of potential SQL sentences, building/transforming them as necessary to work properly under any RDBMS. The number of places using custom (per DB) code should be minimum.

* '''Well documented''': All the functions defined, both at DML and DDL level must be well documented, helping the developer to find and use the correct one in each situation.

== The Stack ==

The next stack shows how Moodle 1.7 code will interact with underlying RDBMS. It will help us to understand a bit more what we are trying to do and will explain some of the points related in the Roadmap (below in this page).

[[Image:MoodleDBStack.png|center]]

Moodle code will use two ''languages'' to perform its DB actions:

* '''XMLDB neutral description files''': To create, modify and delete database objects (DDL: create/alter/drop tables, fields, indexes, constraints...). It consists in a collection of validated, standard, XML files. They will be used to define all the DB objects. New for 1.7.
* '''Moodle SQL neutral statements''': To add, modify, delete and select database information (DML: insert/update/delete/select records). To modify for 1.7.

Please note the '''neutral''' keyword used in the expressions above. It means that both '''languages''' will be 100% the same, independently of the underlying RDBMS being used. And this must be particularly true for the XMLDB part. Point.

Obviously it's possible that in the SQL part we found some specialised queries (using complex joins, regular expressions...) that will force us to do some '''Exceptions'''. Well, they can exist (in fact, they exist), but we always must try to provide an alternate path to minimise them using neutral statements and standard libraries.

Each one of the '''languages''' above will use its own library to do the work:

* '''Moodle DDL Library''' ([[Development:DDL functions|ddllib.php]]): Where all the functions needed to handle DB objects will exist. This library is new for 1.7 and will provide developers with an high level of abstraction. As input it will accept some well defined objects and actions and it will execute the proper commands for the RDBMS being used.
* '''Moodle DML Library''' ([[Development:DML functions|dmllib.php]]): Where all the functions needed to handle DB contents will exist. This library is new for 1.7, although its contents are, basically, functions currently present in '''datalib.php''' (moved from there). All those DML functions will offer cross-db support for insert/update/delete/select statements using a common behaviour.

Also note that '''datalib.php''' continues present in the schema above. It will contain all the functions that haven't been moved to the new '''ddllib.php''' and '''dmllib.php''' libraries. Only some common functions will remain there, and this situation will disappear (it's considered a legacy library) in upcoming '''Moodle''' releases (after 1.7) by moving all those functions to their proper library (course/lib.php, user/lib.php....).

Both these libraries (plus the small '''Exceptions''' bar) will perform all their actions using the '''ADOdb Database Abstraction Library for PHP''' that will receive all the requests from them, communicate with the DB ('''MySQL''', '''PostgreSQL''', '''Oracle''' or '''SQL*Server'''), retrieve results and forward them back to originator library.

== The process ==

This section points to the main areas of information about the '''process of design and implementation''' of the new XMLDB layer:

* [[XMLDB Roadmap|Roadmap]]: Where the whole process is defined. It has been split into small chuncks to be performed and tested easily. Also, such documents should be used to track what's done and what's pending following some easy nomenclature.

* [[XMLDB Problems|Problems]]: A comprensive list of issues that need to be determined/solved prior to incorporating them into the [[XMLDB Roadmap|roadmap]].

== The documentation ==

This section points to the '''main documentation index''' about the implemented XMLDB:

* [[Development:XMLDB Documentation|Documentation]]: Where you'll find quick links to different parts of the XMLDB documentation.

==See also==

=== XMLDB related ===

* [[Development:XMLDB preliminary links|XMLDB preliminary links]] - A collection of links about general info, searched and analysed at the initial stages of the project
* [[Development:XMLDB preliminary notes|XMLDB preliminary notes]] - A collection of notes collected in the early stages of this project, pointing both to some changes required and some problems to solve.

=== Database related ===

* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

[[Category:XMLDB]]

[[zh:开发:XML数据库计划]]

XMLDB introduction

2008-08-06T18:50:07Z

Davidkazuhiro: fixed typo

[[Development:XMLDB Documentation|XMLDB Documentation]] > Introduction
----
__NOTOC__
One of the main upcoming features in Moodle 1.7 will be its ability to work with some more [[wikipedia:RDBMS|RDBMS]] ([[wikipedia:MSSQL|MSSQL]] and [[wikipedia:Oracle database|Oracle]]) while maintaining everything working properly with both [[MySQL]] and [[PostgreSQL]]. As Moodle core uses [http://adodb.sourceforge.net/ ADOdb] internally, this possibility has been present since the beginning and, with the current maturity of the project (5 years old baby!), this can be a good moment to sort all this out.

Initially, all our tests and preliminary work was to inspect how [http://adodb.sourceforge.net/ ADOdb] was doing its work, and how we could mix together all those 4 RDBMS, whose SQL dialects, although pretty similar, have some differences and idiosyncrasies that force us to do some important changes to our current database code (formerly '''datalib.php''') and how it's used by the rest of Moodle.

All the changes to be performed, which primary objective is to enable Moodle to work with more RDBMS must be filled following the next non-functional requirements:

* '''Provide one layer (new) for DB creation/upgrade''' ([[wikipedia:Data_Definition_Language|DDL]]): With this, developers will create their structures in one neutral form, independent of the exact implementation to be used by each RDBMS.

* '''Provide one layer (existing) for DB handling''' ([[wikipedia:Data_Manipulation_Language|DML]]): With this, developers will request/store information also in one neutral form, independent of the RDBMS being used.

* '''Easy migration path from previous versions''': The current installation/upgrade system will work until, at least, Moodle 2.0, allowing 3rd part developers to migrate along the time to the new system.

* '''Simple, usable and effective''': Until now, the way to upgrade Moodle has been really cool and it has worked pretty fine since the beginning, but it has forced developers to maintain at least two installation and two upgrade scripts for each module/plugin. The new alternative will have only one file to install and one file to upgrade (per module/plugin too), reducing the possibility of mistakes in an high degree.

* '''Conditional code usage must be minimised''': Database libraries must accept 99% of potential SQL sentences, building/transforming them as necessary to work properly under any RDBMS. The number of places using custom (per DB) code should be minimum.

* '''Well documented''': All the functions defined, both at DML and DDL level must be well documented, helping the developer to find and use the correct one in each situation.

== The Stack ==

The next stack shows how Moodle 1.7 code will interact with underlying RDBMS. It will help us to understand a bit more what we are trying to do and will explain some of the points related in the Roadmap (below in this page).

[[Image:MoodleDBStack.png|center]]

Moodle code will use two ''languages'' to perform its DB actions:

* '''XMLDB neutral description files''': To create, modify and delete database objects (DDL: create/alter/drop tables, fields, indexes, constraints...). It consists in a collection of validated, standard, XML files. They will be used to define all the DB objects. New for 1.7.
* '''Moodle SQL neutral statements''': To add, modify, delete and select database information (DML: insert/update/delete/select records). To modify for 1.7.

Please note the '''neutral''' keyword used in the expressions above. It means that both '''languages''' will be 100% the same, independently of the underlying RDBMS being used. And this must be particularly true for the XMLDB part. Point.

Obviously it's possible that in the SQL part we found some specialised queries (using complex joins, regular expressions...) that will force us to do some '''Exceptions'''. Well, they can exist (in fact, they exist), but we always must try to provide an alternate path to minimise them using neutral statements and standard libraries.

Each one of the '''languages''' above will use its own library to do the work:

* '''Moodle DDL Library''' ([[Development:DDL functions|ddllib.php]]): Where all the functions needed to handle DB objects will exist. This library is new for 1.7 and will provide developers with an high level of abstraction. As input it will accept some well defined objects and actions and it will execute the proper commands for the RDBMS being used.
* '''Moodle DML Library''' ([[Development:DML functions|dmllib.php]]): Where all the functions needed to handle DB contents will exist. This library is new for 1.7, although its contents are, basically, functions currently present in '''datalib.php''' (moved from there). All those DML functions will offer cross-db support for insert/update/delete/select statements using a common behaviour.

Also note that '''datalib.php''' continues present in the schema above. It will contain all the functions that haven't been moved to the new '''ddllib.php''' and '''dmllib.php''' libraries. Only some common functions will remain there, and this situation will disappear (it's considered a legacy library) in upcoming '''Moodle''' releases (after 1.7) by moving all those functions to their proper library (course/lib.php, user/lib.php....).

Both these libraries (plus the small '''Exceptions''' bar) will perform all their actions using the '''ADOdb Database Abstraction Library for PHP''' that will receive all the requests from them, communicate with the DB ('''MySQL''', '''PostgreSQL''', '''Oracle''' or '''SQL*Server'''), retrieve results and forward them back to originator library.

== The process ==

This section points to the main areas of information about the '''process of design and implementation''' of the new XMLDB layer:

* [[XMLDB Roadmap|Roadmap]]: Where the whole process is defined. It has been split into small chuncks to be performed and tested easily. Also, such documents should be used to track what's done and what's pending following some easy nomenclature.

* [[XMLDB Problems|Problems]]: A comprensive list of issues that need to be determined/solved prior to incorporating them into the [[XMLDB Roadmap|roadmap]].

== The documentation ==

This section points to the '''main documentation index''' about the implemented XMLDB:

* [[Development:XMLDB Documentation|Documentation]]: Where you'll find quick links to different parts of the XMLDB documentation.

==See also==

=== XMLDB related ===

* [[Development:XMLDB preliminary links|XMLDB preliminary links]] - A collection of links about general info, searched and analysed at the initial stages of the project
* [[Development:XMLDB preliminary notes|XMLDB preliminary notes]] - A collection of notes collected in the early stages of this project, pointing both to some changes required and some problems to solve.

=== Database related ===

* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

[[Category:XMLDB]]

[[zh:开发:XML数据库计划]]

Tracker

2008-07-21T01:11:34Z

Davidkazuhiro: /* Logging new issues or improvements */ fixed section header

[[Image:Tracker.jpg]] '''is Moodle's''' [[Image:Issue Tracker MoodleOrg link.JPG]]

Issue tracking is an important part of a continuous quality control process. It involves the reporting of problems (bugs), ideas for improvement and new features. Unlike most proprietary software programs, Moodle issue reporting and tracking information is open to everyone. Moodle's issue tracking system is called '''[http://tracker.moodle.org Moodle Tracker]'''. We welcome your requests for new features, improvements, or even constructive criticism of existing features.

The beauty of open source is that anyone can participate and help to create a better product for all of us to enjoy. Please help us by using [http://tracker.moodle.org Moodle Tracker]!

==Basics==
===Logging in to Tracker===
*If you're a new Tracker user, create a user account [http://tracker.moodle.org here]. It is strongly suggested your Tracker username is the same name you use at Moodle.org.
*If you've forgotten your password, go [http://tracker.moodle.org here] and select '<u>forgot password</u>' which is just under the 'log in' button. Follow the prompts.

=== Summary: How to report a bug, improvement, or new feature request ===
NB See the section 'Tracker fields' below for a full description of every field.
*Login to [http://tracker.moodle.org Tracker]
*Select "Create New Issue" from the menu under the Moodle Tracker logo
*From the dropdown menu select the "Issue type": Bug, New Feature, Task or Improvement
*You will see a series of dropdown and free text fields. Complete as many as you can. Some fields are required while others are optional.
*Press the 'Create' button at the bottom of the page to create the bug.

=== How to write a good Tracker entry===
A good report will include:
*Summary (describe the issue in 1 or 2 sentences)
*Description (a concise yet complete summary of the problem or improvement)
*Steps to Reproduce: A detailed, easy-to-follow sequence of steps a developer can follow to reproduce the problem. If possible, provide a URL so a developer can see the problem with one click.
*Actual Results: What the application did after performing the above steps.
*Expected Results: What the application should have done, were the bug not present. Provide as much detail as possible. Your expectation might mean that help instructions need to be improved or interface changed.

If possible, include additional information that may be helpful to the developer:
*Moodle version (there is a dropdown menu on the top of the form, if that does not have what you want, add it in the description)
* If you have an error message, or information in your PHP or web server logs, copy and paste it into the bug report. If you can, turn on "debug" in your Admin configuration page and reproduce the problem to get the best possible error message.
* Screen shots are very helpful for some bugs, but please write a textual description of the problem too.
* Provide details about your setup including operating system, database, etc. If you run out of room in the environment section, add more detail in the description. The full set of information that might be relevant is:
**Server operating system type and version number
**Web server type and version number
**PHP version number (and whether you are using an accelerator)
**Database type and version number
**Client-side operating system type and version number
**Web browser type and version number

* You don't need to provide details all the time. For example, for a layout rendering problem, you need to give only the client-side OS and browser info, and if it is a server-side problem you only need to describe the setup there. Use your judgment. Here are some examples:
**I see this bug with the latest Moodle HEAD running on PHP5.1.2/Apache 2.2.3 on Linux. My database is Postgres 8.1.
**This rendering problem happens using Internet Explorer 6.0 on Windows XP.

In summary stick with facts and present enough facts so someone else can duplicate the problem.

Here are some examples of good bug reports: MDL-6030, MDL-5688, MDL-12505

*A good external reference to help write a tracker entry can be found at [http://developer.mozilla.org/en/docs/Bug_writing_guidelines mozilla bug writing guidelines].

"What’s the hardest thing about a bug report?" Most of the time fixing the problem is the easy part, the hard part is reproducing the bug. The developer needs to see how it is broke to be able to fix it. If they can't reproduce the error you can be sure they won't be able to fix it!

Good bug reports contain as much detail as possible and are specific. Don't generalise or leap to conclusions.

For example, a bug report that only says "The RSS feed doesn’t support UTF-8" is not helpful. The developer knows that UTF-8 and RSS feeds are compatible. The developer has no idea of what the person sees and why they reported this bug. In this case more time and effort needs to be expended to determine the problem.

Consider a bug report which says that the descriptions for the specific RSS feed XYZ@abc shows unrecognisable characters rather than expected characters.

==Tracker process==
===Logging new issues or improvements===
Anyone with a Tracker account can log issues. See instructions above for writing good quality bug reports. It is important that you search Tracker to determine if your problem or suggestion for improvement has already been reported. If it has you are encouraged to add more information (use the "comment" function), vote for the issue, or watch it (more on this later).

You will receive an email when you log a new bug or make updates to bugs you've reported. You'll also receive notification when updates are made to bugs you're watching.

You can monitor, or '''watch''' issues reported by others. To do this, open the issue, then select "Watch it" from the left hand navigation panel. To add others to the watchlist for your issue, open the issue, select the option "Watching" from the left hand navigation panel. These people will receive email notification when the issue is updated.

Tracker provides a facility to '''Link''' issues. Any user logged onto Tracker may link issues. Multiple link types are defined in the system; you will be required to select one when linking bugs. See [insert section name] for detailed list of link types.

'''Vote''' for bugs you want to see addressed in Moodle. Any user can vote. To vote for a specific bug, browse to the bug, then select "Vote for it" from the left-hand navigation panel. Developers may consider the number of votes a bug has when weighing the merits of two or more bugs.

The Tracker '''Dashboard''' is flexible and customisable depending on your area of interest. For instructions on configuring the Tracker dashboard click [http://www.atlassian.com/software/jira/docs/v3.6.3/dashboard.html here].

The Tracker '''Issue Navigator''' is used to find and filter bugs. For instructions on configuring the Issue Navigator click [http://www.atlassian.com/software/jira/docs/v3.6.4/navigatorcolumns.html here].

Tracker's '''Quick Search''' function is explained [http://www.atlassian.com/software/jira/docs/v3.6.4/quicksearch.html here]

===Resolving issues===
(this section should be reviewed)
Issues are resolved in Tracker to show that they've been actioned. Only Moodle core developers and testers are permitted to change the status of bugs in Tracker to "resolved" or "closed".

This is the general process a developer will follow when actioning a Tracker issue:

# Issues are automatically assigned at the time they're created based on component type; they may be reassigned by developers or Component Leads.
# Developers fix, modify or add code and check into CVS. The Tracker issue number is included which automatically links the CVS change to Tracker.
# Patches are attached to Tracker issues so that they may be verified and possibly included in CVS.
# Appropriate comments should be added in Tracker describing the fix. The bug's status is changed to '''Resolved'''.
# The developer should indicate which version of Moodle the change will be included in using the '''Fix Version/s'''. You should use this to indicate which branch(es) you checked the fix into (example below).
# The only exception to not moving a bug to Resolved is if a developer believes there is no value in testing the resolved issue, in which case the bug status can be changed to Closed.

===Testing issues===
All users are encouraged to be active participants when it comes to testing Moodle. Anyone with a Tracker user account can log, view, comment on, vote, and watch bugs. If you find bugs or problems, have ideas for improvements, or want additional functionality added to Moodle, please log a bug in Tracker.

We've formalised a group of testers in Tracker who are responsible for verifying the accuracy of changes made by developers. These testers have responsibilities and authority in Tracker beyond that of standard users. Testers normally have a good understanding of Moodle, and are active in the Moodle community. Obviously testers should have the skills and knowledge to sufficiently test the issue - experience is important - but don't forget there are others in the Moodle community who may be willing to lend a hand. If you are interested in becoming a member of the Moodle Testing team, make yourself known by logging a request through Tracker. We'd love to have you join the team! Log your request at the [http://tracker.moodle.org/secure/project/ViewProject.jspa?pid=10020 Moodle.org Sites] Tracker project.

<u>Testing a bug in Tracker</u>

NB This is the process members of the moodle-testers group should follow to move bugs from 'resolved' to 'closed'.
*Testers test bugs with Status=Resolved. Global filters have been created based on upcoming releases (eg 1.7 Resolved) to make identification simple.
*Use the '''QA Assignee''' field to identify yourself as the tester of a particular bug.

*It's a good idea to add your name to the watch list for all bugs you test. (see "Tracker watch list", below.)
*If the bug passes testing, close the bug using the "Close Issue" button. You must add appropriate '''comments''' describing your testing methods, any issues that were found, etc.
*If the bug fails testing or if you feel the fix is incomplete, '''reopen''' the bug using the "Reopen Issue" button. Ensure the bug is assigned to the correct developer. Work with the developer to find a mutually agreeable resolution to the bug.
*A release will be deemed ready when all bugs fixed for a particular version have been closed.
*All resolved bugs should be tested. Bugs with a resolution code of "fixed" represent bugs where code has been updated, and probably represent more of a challenge than bugs with resoluton codes of duplicate, won't fix, and not a bug, and can't reproduce. Please ensure bugs have been closed with a proper resolution code. Unfortunately it's not easy to change a resolution code in Tracker once the bug has been resolved (the only way is to reopen, then re-resolve).
*Don't be afraid to discuss your testing with the developer assigned to the bug. Simply adding a comment should get the attention of the developer as they are notified of all changes.

==Detailed description of Tracker fields and groups ==
===Tracker fields===
NB A short explanation appears under each field in Tracker.

'''Project''' - Required field. Tracker is a collection of multiple projects. At present there are 3: 'moodle', 'moodle.org sites' and 'Non-core contributed modules'. Specify 'moodle' for issues/bugs related to moodle software; specify 'moodle.org sites' for issues/bugs related to tracker.moodle.org, docs.moodle.org, demo.moodle.org, download.moodle.org, or moodle.org; specify 'Non-core contributed modules' for issues/bugs related to contributed modules.

'''Issue Type''' - Required field. Bugs are classified as 1 of the following:
:''Bug'' - A problem which impairs or prevents Moodle from functioning correctly.
:''Improvement'' - An enhancement to an existing Moodle feature.
:''New Feature'' - A new Moodle feature which has yet to be developed.
:''Task'' - A task that needs to be completed. Tasks usually refer to work that must be done outside the product.
:''Sub-Task'' - Issues are sometimes broken into multiple sub-tasks.

'''Summary''' - Required field. A brief, concise description of the problem.

'''Security Level''' - Optional field. Specify if this bug or change has security implications for Moodle. Bugs with serious security implications are restricted so that only members of the moodle-security group can see them.

'''Priority''' - Bugs are prioritised using one of the following:
:''Blocker'' - Blocks development and/or testing work, production could not run.
:''Critical'' - Crashes, loss of data, severe memory leak.
:''Major'' - Major loss of function.
:''Minor'' - Minor loss of function, or other problem where easy workaround is available.
:''Trivial'' - Cosmetic problem like misspelled words or misaligned text.

'''Component/s''' - Required field. Select the area in Moodle which is affected by this bug. Select 'Unknown' if you are unsure.

'''Affects Version/s''' - Required field. This is the Moodle version in which the bug has been found. It is entered by the person logging the bug, and typically only 1 version is specified. Enter your current version when logging an 'improvement', 'task', or 'new feature' as this will help assess the state of the product when the request was made.

'''Assigned To''' - This is the person who will fix (code) the issue. Tracker automatically assigns issues to Component Leads. Developers or QA Testers can reassign issues.

'''Reporter''' - The person who logs the bug. This field is automatically filled by Tracker.

'''Environment''' - Specify the operating system, software platform and/or hardware specifications if applicable to this bug.

'''Description''' - A full and complete yet concise description of the problem or improvement.

'''Database''' - Optional field. If applicable to the bug, identify the database type.

'''URL''' - Optional field. If possible, provide a URL address that demonstrates an example of this bug.

'''QA Assignee''' - Used to designate the person who will test this issue.

'''Fixed Version/s''' - This is the Moodle version the bug was or will be fixed in. Basically you should think '''Which release notes should this appear in?''' This field is normally completed by the developer when the bug has been resolved or by lead developers allocating bugs for a specific release. Normally only one version is specified in this field. It symbolises the ''first'' version of Moodle where the change will be seen.
:Example: after Moodle 1.9 has been released, if you fix a bug on the MOODLE_19_STABLE and HEAD branches, mark it as fixed in 1.9.1. If you also backported to MOODLE_18_STABLE, then add the version of the next 1.8.x release too.

:If you resolve the bug as anything but "Fixed" (Cannot Reproduce, Won't Fix, etc.) leave Fix Version/s blank.
:If you resolve the bug as Duplicate, then create a link to the duplicate issue.
:These Fix version/s are used to automatically build release notes (see the tabs on http://tracker.moodle.org/browse/MDL).

'''Attachment''' - Optional. Attach a file that will help developers and testers better understand the bug. Maximum attachement size is 512Kb.

'''Comment''' - The comment field is a detailed register of all changes that relate to this bug.

'''Resolution''' - This field is only displayed when resolving or closing a bug. Specify a code that best describes how this bug was resolved.
:''Fixed'' - Bug has been fixed; a code change will be checked into CVS. Use this resolution code only when actual changes were made to Moodle code.
:''Won't Fix'' - The problem described is an issue which will never be fixed.
:''Not a bug'' - This issue is not a bug; was logged in error. Use this code if the bug was fixed by another bug report or in some earlier Moodle version.
:''Duplicate'' - The problem is a duplicate of an existing issue.
:''Incomplete'' - More information is needed to understand this bug.
:''Can't Reproduce'' - All attempts at reproducing this issue failed, or not enough information was available to reproduce the issue. Reading the code produces no clues as to why this behavior would occur. If more information appears later, please reopen the issue.
:''Deferred'' - The resolution to this bug will be deferred to a later release.

=== Tracker groups and permissions ===
'''Standard Users''' [groupname=jira-user] - This is the default group. New user accounts are placed in this group at the time of creation, and users must be a member of this group in order to log into Tracker. Members of this group can browse bugs, create new bugs, comment on bugs, create attachments, create sub-tasks, create filters, watch bugs, and vote for bugs. Members of this group can also resolve bugs, which is primarily a way of closing bugs that are no longer relevant (eg duplicates, or logged in error). Standard Users can configure their Tracker workspace by using the "Configure your Issue Navigator" button. This feature allows users to view watch and voting lists and to manage preferences, profile, and password.

'''Developers''' [groupname=jira-developer] - Developers can do everything Standard Users can do. In addition they can clone bugs, close bugs, edit bugs, link bugs, and assign bugs. Members of this group can also use the Bulk Edit function which allows bulk updated to multiple bugs.

'''Testers''' [groupname=moodle-testers] - Testers can do everything a Developer can do.

'''Moodle Security groups''' [groupname=moodle-security] - Trusted developers and administrators who need to work on and learn about security issues.

"Nobody" is a Tracker user created to alert users to the fact that an issue hasn't been assigned to a developer. These issues are regularly reviewed by the team at Moodle HQ.

NB You can browse a project while not logged in to Tracker, however you will be unable change/edit/comment on bugs.

=== Link types ===
The following link types are available:
::duplicates - duplicates are inevitable in a project the size of Moodle. They occur when a logger is unaware of an existing bug that describes the same problem. Use ''duplicates'' to link to the first or most comprehensively described instance of the problem. All duplicates should be linked together.
::blockers - use this to identify bugs that block others from being fixed.
::cloners - in some instances a duplicate bug is intentionally created in order to track the fix in another branch of the code - this almost never is used in the Moodle project.
::dependency - often a fix is dependent on another bug being resolved first, on in a specific order.
::relates - used to identify a bug that is somehow related to another bug.
'''Don't be afraid to link bugs. ''' Links are bi-directional meaning that there's a concept of 'inward' and 'outward' - it affects how linked bugs are displayed. This is why you'll see "blocks/is blocked by" or "duplicates/is duplicated by" in the drop down list of the ''Link Issue'' dialog. Don't become too concerned about using the "correct" link type - all link types work similarly.

==See also==

*[[Development:Weekly Code Review]]
*[http://www.atlassian.com/software/jira/ Jira] Tracker is a slightly customised version of Atlassian's product
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=43952 How to manipulate Moodle developers] forum discussion
*Wikipedia [http://en.wikipedia.org/wiki/Software_bug Definition of a bug]

[[Category:Teacher]]
[[Category:Administrator]]
[[Category:Developer]]
[[Category:Developer tools]]

[[pt:Tracker]]
[[es:Sistema de bugs]]
[[fr:Traqueur de bogues]]

GIFT format

2008-05-22T18:27:13Z

Davidkazuhiro: removed german

With GIFT format you can write multiple-choice, true-false, short answer, matching and numerical questions in a text editor in a simple format. For large numbers of questions, GIFT is likely to provide the quickest way of bulk loading your questions.
[[Image:Gift.jpg|frame|left|screen shot from quiz help file documentation]]<br style="clear:both;">

At least one blank line must be left between each question.

Here is an [http://moodle.org/file.php/5/moddata/forum/121/236161/GIFT-examples.zip GIFT example] for quiz-import, easy to copy and change ...

The file '''must''' be correctly encoded in [[UTF8]]. Beware of some of Microsoft's "fake" Unicode implementation which is not compatible and may result in strange characters appearing in your quizzes.

Here is a 2-column GIFT format reference sheet I created for a training:
*[http://buypct.com/gift_reference.pdf GIFT Reference Sheet]

===Hints and Tips===

* Use the ::title:: at the beginning of every question to organize this for you (01 - testquestion), otherwise it would be difficult to find the right question for changes, moodle will take the beginning of every question as internal title.
* In the Lesson module, in a question page, correct answers jump by default to Next page and incorrect answers jump to This page (i.e. student has to "try again"). When importing from a GIFT format file, this is exactly the mechanism which is used.
* If you want a student to be taken directly from one question to the next irrespective of their answer being correct or incorrect: in the Lesson Settings, set Maximum number of attempts: to 1. Please note, however, that a message "correct / incorrect" will still be displayed to the student upon answering each question. If you do not want this (default) feedback message to be displayed then enter your own feedback message (i.e. "continue", "---", etc.) In case you want no visible message displayed then enter a non-breaking space as feedback, so you'll have to put a # after the answer which may be ~3 and '''write & n b s p ; after that.(without spaces between these characters)'''
* If you want to use curly braces, { or }, or equal sign, =, or # or ~ in a GIFT file (for example in a math question including TeX expressions) you must "escape" them by preceding them with a \ directly in front of each { or } or =. It is possible to use a replace program/macro/editor filter to do this conversion before importing to Moodle.
* There are Word macros available for easily creating GIFT files. See [http://www.soberit.hut.fi/sprg/resources/moodle/GiftConverter.html].
* Here's an Excel spreadsheet for generating multiple choice GIFT files [http://moodle.org/mod/forum/discuss.php?d=45245] and a newer version that supports other question formats (be sure to scroll down to the most recent version) [http://moodle.org/mod/forum/discuss.php?d=66660].
* Here's an Open Office template for generating GIFT files. [http://moodle.org/mod/forum/discuss.php?d=20705&parent=168385]

==See also==

*[[Export questions]]
*[[Import questions]]
*[[Aiken Format]]
*[[Moodle XML format]]

[[Category:Questions]]