MoodleDocs - User contributions [en]

Projects for new developers

2015-12-29T00:19:48Z

Chuang: /* Getting started */

{{GSOC}}

==Getting started==

Moodle uses PHP, JavaScript, SQL and a number of other Web languages, so learning those is a good place to start.

When you have some basic PHP programming skills, you may wish to start learning about how the Moodle code is organised. It is recommended that you complete the [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming] course on [http://dev.moodle.org/ dev.moodle.org]. To access this you will need to have an account on moodle.org first.

''If you are looking for projects suggested in the tracker, look for issues with the [https://tracker.moodle.org/issues/?jql=labels%20in%20%28addon_candidate%29 'addon_candidate' label].

''If you are looking to make a quick contribution, look for tracker issues with marked as [https://tracker.moodle.org/issues/?jql=Difficulty%20%3D%20Easy easy].

''Please consider adopting a [https://moodle.org/plugins/browse.php?list=set&id=61 plugin seeking a new maintainer]''. See the [https://moodle.org/mod/forum/discuss.php?d=260354 Plugins adoption programme].

As you become more involved in Moodle development, you might like to learn more about the [[Coding|coding conventions]] used and how changes to Moodle core code are [[Process|processed]].

==Potential projects==

This evolving page lists possible Moodle projects for new developers derived from community suggestions.

''If you have any ideas for new features in Moodle which might be suitable as projects for new developers, please see [[New feature ideas]].''

=== Plagiarism plugin (Moorsp) ===

There are various commercial plugins available that use the Plagiarism API in Moodle, but because these plagiarism systems can require paid subscriptions, testing them can be difficult. I'd like to see a basic plugin developed (called Moorsp) that could be used for testing the Plagiarism API and provides a structure that can be built on in future to add further functionality.

The initial aim of this project is not to develop a new Plagiarism checking tool but to develop a tool that provides complete Behat and unit tests for the Moodle Plagiarism API.

All files uploaded to Moodle are stored on disk using the contenthash of the file as the filename - this means that if a user uploads the exact file multiple times in different locations only one file is stored on disk. The plugin should implement a check to see if the exact file has been submitted to any other courses/activities and display related information if another match has been found.

Existing Plagiarism plugins (turnitin, urkund, compilatio etc) make use of the legacy log feature of the events api - the new plugin should use the new api and not rely on legacy logs.

Deliverables:
* All Plagiarism API functions should be implemented.
* Support for Assign, forum and Workshop modules should be implemented.
* Full Unit test coverage of all plugin functions.
* Full Behat tests for Assign, forum and workshop modules should be implemented to ensure that all Plagiarism API functions are working as expected.
* The code should pass 100% of the Moodle codechecking tools to ensure the code meets with Moodle Guidelines.
* The code should perform well with appropriate use of the Moodle caching tools.

Future Improvements (outside scope of initial project)
* Add Plagiarism API to the Moodle Glossary plugin.
* Implement functions that allow the plugin to post content to an external source - a future open source moorsp server that will receive content and generate a similarity report - we may be able to re-purpose some of the code from the old plagiarism_crot plugin to do this.

This project was proposed in previous GSOC years and some useful information is available in the older discussion [http://dev.moodle.org/mod/forum/discuss.php?d=1822 here]

:'''Skills required''': PHP
:'''Difficulty level''': Medium
:'''Possible mentor''': [http://moodle.org/user/view.php?id=21591&course=5 Dan Marsden]
:'''Message from the mentor''': [http://dev.moodle.org/mod/forum/discuss.php?d=2280 Tips for applying to the moorsp project]
:'''Initial code structure''': [https://github.com/danmarsden/moodle-plagiarism_moorsp]

=== Improved enrol_meta plugin ===

Current enrol_meta plugin provides functionality to automatically synchronise enrolments between two courses. See [https://docs.moodle.org/en/Course_meta_link Course meta link]. Teacher creates an instance of enroment method in the meta course and links it to one child course. Later cron job ensures that any enrolment change in the child course is pushed to the parent.

Unfortunately user interface is very inconvenient. The main problem is inability to bulk select courses and/or order courses on the Enrolment methods page. Plus it lacks important functionality to synchronise suspended/expired enrolments. See the number of highly voted issues MDL-27628, MDL-17929, MDL-32161, MDL-31451

The proposal is to re-write this enrolment plugin completely. One instance of the plugin should allow to link multiple child courses and additionally synchronise each of them with a group in the meta course. Ideally it should also allow to synchronise all courses in the category.

This project requires development of both user interface (JS) and backend (PHP).

:'''Skills required''': PHP, Javascript (YUI)
:'''Difficulty level''': Medium
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=1334243 Marina Glancy]

=== Allow to crop/resize/rotate images when inserting them ===

This project is inspired by MDL-32183. There are two options on how to implement this functionality - as a repository plugin or as an atto plugin.

:'''Skills required''': Javascript (YUI), PHP
:'''Difficulty level''': Medium
:'''Possible mentor''': [https://moodle.org/user/profile.php?id=1334243 Marina Glancy]

==See also==

* [[GSOC]] - describing Moodle's involvement with Google in their Summer of Code program
* [http://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=type+in+%28%22New+Feature%22%2C+Improvement%29+AND+resolution+%3D+unresolved+ORDER+BY+votes+DESC&runQuery=true&clear=true Popular new feature and improvement requests in Tracker]
* [[Projects for new developers/Archive|Archive]] of outdated and/or inactive calls for projects

SCORM schema

2013-07-24T20:25:04Z

Chuang: /* View an activity */

This page explains the files involved in displaying a SCORM package - it is mainly useful for developers.

The names of files in the images below are a slightly out of date compared to 2.0, however the concept is still the same.

== How player works ==

[[Image:Scorm1.5schema.gif]]

==Insert and update an activity==

[[Image:Scorm insert update.png]]

==View an activity==

[[Image:Scorm view.png]]

==SCORM Database Tables==

In Moodle 2.5.x, there are 11 database tables that are related to SCORM:

* mdl_scorm: Include id, course, name, scormtype, reference, intro, introformat, version, maxgrade, grademethod, etc.

* mdl_scorm_aicc_session: This is a new table that did not exist in Moodle 2.0.x. Include id, userid, scormid, hacpsession, scoid, scormmode, scormstatus, attempt, lessonstatus, sessiontime, timecreated, timemodified.

* mdl_scorm_scoes: has id, scorm, manifest, organization, parent, identifier, launch, etc.

* mdl_scorm_scoes_data: has id, scoid, name, and value. That's it.

* '''mdl_scorm_scoes_track:''' has id, userid, scormid, scoid, attempt, element, value, timemodified.
==> For most developers you probably would be interested in this table.

* mdl_scorm_seq_mapinfo:

* mdl_scorm_seq_objective:

* mdl_scorm_seq_rolluprule:

* mdl_scorm_seq_rolluprulecond:

* mdl_scorm_seq_rulecond:

* mdl_scorm_seq_ruleconds:

[[Category:SCORM]]

User:Wen Hao Chuang

2013-04-21T08:52:41Z

Chuang:

I'm one of the Moodle developers / most helpful Moodlers in the Moodle community. Currently I'm working as an "Academic Technology Consultant" at San Francisco State University (full-time), and teaches part-time in the department of Instructional Technology (ITEC).

Feel free to check out my Linkedin page at http://www.linkedin.com/in/wchuang

For more info about me please read my profile on moodle.org

http://moodle.org/user/view.php?id=18123

Wizard

2011-10-05T20:42:44Z

Chuang: /* Problem */

[[ Moodle User Interface Guidelines|Moodle User Interface Guidelines]] > '''Wizard'''

== Problem ==
* Users need to perform a complex task, with which they are not familiar or lack needed domain knowledge
* The task users need to perform naturally divides into subtasks, and the nature or number of subtasks depends on what is selected in some other (preceding) tasks

== Context ==
You are designing an UI for users who are not experts at a given task that involves entering a lot of information or making intricate selections that depend on each other.
== Forces: factors that affect selection ==
* Unexperienced users may get frustrated
** if too many choices, dependent on each other, are presented to them at once
** if they do not have all the background information related to a task
* Experienced users easily get frustrated
** if a task they know is split into too many phases
** if the order they enter data into the application is controlled
* Any user can be frustrated by lack of control in the process, i.e. not knowing the number of steps left or not being capable of controlling the process (returning back in the process to an earlier screen in case of a misunderstanding or mistake, for example)

== Solution ==

A Wizard, sometimes called an Assistant, is an interface that guides users through a predefined sequence of steps.

=== Elements of a wizard ===

==== Status display ====
Displays the steps required to complete the wizard, and indicates the step the user is in currently, giving important feedback to the user resulting from their actions, making the application seem responsive.

==== Navigation buttons ====
* '''Previous''': Whereever it is possible to allow the user to change the selections they have already made, a button labeled 'Previous' should be provided.
** Obviously, the first page of the wizard does not include a previous button, nor do pages which are a result of actions that can not be undone.
** Unlike one might assume, the Previous button acts as a submit button for the current page, just like the Next button. If the user has made changes on the current page when they decide to return to a previous step, those changes are saved.
**Provide a Previous button whenever possible to maximize user control.
* '''Next''': Used for moving to the next step
** When the next step is to actually start an operation (usually the last step of the wizard), the button is in the same position, but the label is an action verb such as "Start Backup". This is to let users know that they are doing something that actually has consequences and not just continuing to enter data. If the operation that the user is about to start cannot be undone or is in some other way potentially dangerous, consider adding a javascript warning dialog confirming the user wants to continue.
* '''Cancel''': If there is a specific page from which the user can be assumed to have arrived to the wizard from, clicking Cancel will return them to this page. If you can not be sure, determine a reasonable default.
** The Cancel button should in most cases (except in very simple Wizards) have a javascript confirmation dialog associated with it, noting them that all the information they have entered will be lost, and asking them if they really want to continue.

=== Notes ===
The user should be capable of using the browser's back button normally in a wizard.
* After pressing the Next button, the user should end up in the step that was before the page
* After pressing the Previous button, the user should end up in the step that is after the current step in the wizard's sequence
* If the user cannot return to the previous step anymore, the user should be returned to the earliest possible screen, or alternatively the wizard should be reinitialized and the user sent to the first page of the wizard

If there is a danger that experienced users want to use the functionality provided by the wizard and that they want more control than what the wizard provides, provide an alternate user interface to them.

== Common mistakes ==

Moodle Wizards typically do not have all of the required buttons nor the status display.

Each screen is a form, so no links are used for moving between the screens but the next/previous should be used. The added click of selecting a form field and then pressing 'next' is secondary to the problem of potentially losing user data: even if the data is preserved (using javascript which cannot be relied upon anyway), navigation links do not afford this so the user is left anxious. Also usage of back/forward browser buttons is problematic if what user has selected is not saved in the session using a the next/prev buttons (which are technically form submit buttons).

== Examples and implementation ==

=== Backup ===

[[Image:wizard-mockup.png|thumb]]
This mockup (MDL-20036) demonstrates the main features of a wizard.
* Status display and controls for controlling the wizard
* The visual hierarchy of the page expresses that the content in the box with the darker background is part of the wizard, and that this wizard is completes the process of backing up the Course Course Fullname 101.

Note that this wizard is in the sense not typical that it only contains one step where the user actually does anything actively (enters information). The fact that the single screen contains a lot of information may slow down novices, but since backup can be considered an advanced operation, slowing down more experienced users would be worse.

* '''Note''': Moodle 2.0 contains a implementation of a wizard done according to MDL-20036 (see MDL-22142). View it at http://qa.moodle.net/backup/backup.php?id=1 (requires login with the qa site testing credentials). A screenshot should be added here as soon as Moodle 2.0 is released.

'''Further examples and code samples: [[Wizard Examples and Code Samples]]'''

== Related guidelines ==
Another way of only showing unexperienced users what they understand is using [[Progressive_Disclosure|Progressive Disclosure]]

== Related issues in the tracker ==
* TODO: all the issues with installation and backup

== (Optional) Further information / Sources ==
* GNOME HIG: [http://library.gnome.org/devel/hig-book/stable/windows-assistant.html.en Assistants]
* http://ui-patterns.com/pattern/Wizard
* http://www.welie.com/patterns/showPattern.php?patternID=wizard
* http://uipatternfactory.com/p=wizard/
* http://en.wikipedia.org/wiki/Wizard_(software)

[[Category:Moodle User Interface Guidelines]]

Blocks

2011-02-24T17:44:24Z

Chuang: minor typo correction

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

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

{{Moodle 1.9}}

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/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/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 ''/blocks/simplehtml/'' and creating a file named ''/blocks/simplehtml/'''''block_simplehtml.php''' which will hold our code. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

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/Appendix_A#init.28.29| 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/Appendix_A#.24this-.3Etitle| $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#Eye_Candy| how to disable the title's display]].

[[Blocks/Appendix_A#.24this-.3Eversion| $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/Appendix_A#.24this-.3Eversion| $this->version]] to '''YYYYMMDD00''' and forget about it.

'''UPDATING:'''<br />
Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

{{Moodle 2.0}}

If you are using Moodle 2.0 and starting to develop your own block. You have to put the version information of the block in a separate file named version.php in ''/blocks/simplehtml/'''''version.php'''. This file has no reference in its name or content to the block's name (simplehtml).

Moodle 2.0 will also require a name for your plugin to show in the upgrading page. You set this value in a language package (the same file where you put your string for the plugin title). Create the file ''/blocks/simplehtml/lang/en/'''''block_simplehtml.php''' and paste the following code:

<code php>
<?php
$string['pluginname'] = 'Simple html block';
$string['simplehtml'] = 'Simple html';
</code>

== 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:

<code php>
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;
}
} // Here's the closing curly bracket for the class definition
// and here's the closing PHP tag from the section above.
?> </code>

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/Appendix_A#.24this-.3Econtent| $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 (Click "Notifications" under the Site Administration Block) 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:

<code php>
function instance_allow_config() {
return true;
}
</code>

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:

<code php>
<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(); ?>
</code>

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 '''config_instance.html''' 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/Appendix_A#init.28.29| init()]].

In the event where the default behaviour 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/Appendix_A| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Blocks/Appendix_A#.24this-.3Econfig| $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 ''/blocks/simplehtml/block_simplehtml.php'':

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

and change it to:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
</code>

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:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';
</code>

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.

{{Moodle 2.0}}

In Moodle 2.0 there is a simpler way to create the interface to configure your block. Instead of creating the <span class="filename">/blocks/simplehtml/'''config_instance.html'''</span> file, you have to create a <span class="filename">/blocks/simplehtml/'''edit_form.php'''</span> file which contains only php code and no HTML. Moodle will process this file and add its elements to the configuration page for your block.

Create the edit_form.php file and paste the following code:
<code php>
<?php

class block_simplehtml_edit_form extends block_edit_form {

protected function specific_definition($mform) {

// Section header title according to language file.
$mform->addElement('header', 'configheader', get_string('blocksettings', 'block'));

// A sample string variable with a default value.
$mform->addElement('text', 'config_text', get_string('blockstring', 'block_simplehtml'));
$mform->setDefault('config_text', 'default value');
$mform->setType('config_text', PARAM_MULTILANG);
}
}
</code>
The first line declares a class that inherits from block_edit_form, this allows Moodle to identify the code to execute in the configuration page. The specific_definition function does two things: It indicates the header for the configuration section, which in this case we took from the 'blocksettings' string for blocks. The second part is where you define the variables that will be defined in the config part of your block. Three lines define this: The first one adds an element, each element is a variable within config, that is of text type, and is described by the blockstring string in the language file for the simplehtml block. The second line indicates a default value (in case it is not yet defined). The third line sets a type for our variable, in this case PARAM_MULTILANG.
{{Top}}

== 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:

<code php>
<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>
</code>

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 weird, if we think back a bit. Do you remember that [[Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
function specialization() {
if (!empty($this->config->title)) {
$this->title = $this->config->title;
} else {
$this->config->title = 'Some title ...';
}
if (empty($this->config->text)) {
$this->config->text = 'Some text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Blocks/Appendix_A#specialization.28.29| 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/Appendix_A#init.28.29|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/Appendix_A#specialization.28.29| 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/Appendix_A#get_content.28.29| get_content()]] 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 (<nowiki>''</nowiki>). Moodle performs this check by calling the block's [[Blocks/Appendix_A#is_empty.28.29| 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/Appendix_A#hide_header.28.29| 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:

<code php>
function instance_allow_multiple() {
return true;
}
</code>

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/Appendix_A#instance_allow_multiple.28.29| instance_allow_multiple()]] method, the method [[Blocks/Appendix_A#instance_allow_config.28.29| 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/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] method now without harm. We had only needed it when multiple instances of the block were not allowed.

{{Top}}

== 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:

<code php>
function has_config() {
return true;
}
</code>

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:

[[Development_talk:Blocks|TODO: New settings.php method]]
: Just to note that general documentation about admin settings is at [[Admin_settings#Individual_settings]]. In the absence of documentation, you can look at blocks/course_list, blocks/online_users and blocks/rss_client. They all use a settings.php file.--[[User:Tim Hunt|Tim Hunt]] 19:38, 28 January 2009 (CST)

<code php>
<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>
</code>

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").

=== config_save() ===

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/Appendix_A#config_save.28.29| config_save()]], the default implementation of which is as follows:

<code php>
function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
</code>

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:

<code php>
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;
}
</code>

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.

===String me up ===

Now that we have a working config_global with saved values we want to be able to read the values from it. The simplest way to do this is to assign the config setting to a string and then use the string as we would any other. IE;

$string = $CFG->configsetting;

You can check all the configuration settings available to a module by displaying them all with;

print_object($CFG);

{{Top}}

=== instance_config_save() ===

Much as we did just before with overriding [[Blocks/Appendix_A#config_save.28.29| config_save()]], what is needed here is overriding the method [[Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] which handles the instance configuration. The default implementation is as follows:

<code php>
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);
}
</code>

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:

<code php>
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);
}
</code>

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?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise 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/Appendix_A#get_content.28.29| get_content()]] method.)

=== UPDATING: ===
Prior to version 1.5, the file ''config_global.html'' was named simply ''config.html''. 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:

<code php>
function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks/Appendix_A#init.28.29| 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:

<code php>
function preferred_width() {
// The preferred value is in pixels
return 200;
}
</code>

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 <div> or <table> elements, 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

<code php>
function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
</code>

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/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

===and some other useful examples too:===
<code php>
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());
}
</code>

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:

<code php>
function html_attributes() {
$attrs = parent::html_attributes();
// Add your own attributes here, e.g.
// $attrs['width'] = '50%';
return $attrs;
}
</code>

== 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:

<code php>
function applicable_formats() {
return array('site' => true);
}
</code>

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:

<code php>
function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

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:

<code php>
function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

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:''' <br />
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/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== Responding to Cron ==

It is possible to have your block respond to the cron process. That is have a method that is run at regular intervals regardless of user interaction. There are two parts to this. Firstly you need to define a new function within your block class:

<code php>
function cron() {
mtrace( "Hey, my cron script is running" );

// do something

return true;
}
</code>

Then within your init function you will need to set the (minimum) execution interval for your cron function.

<code php>
$this->cron = 300;
</code>

Will set the minimum interval to 5 minutes. However, the function can only be called as frequently as cron has been set to run in the Moodle installation. Remember that if you change any values in the init function you '''must''' bump the version number and visit the Notifications page otherwise they will be ignored.

'''NOTE:'''
The block cron is designed to call the cron script for that block '''type''' only. That is, cron does not care about individual instances of blocks. Inside your cron function although $this is defined it has almost nothing in it (only title, content type, version and cron fields are populated). If you need to execute cron for individual instances it is your own responsibility to iterate over them in the block's cron function. Example:

<code php>
function cron() {

// get the block type from the name
$blocktype = get_record( 'block', 'name', 'my_block_name' );

// get the instances of the block
$instances = get_records( 'block_instance','blockid',$blocktype->id );

// iterate over the instances
foreach ($instances as $instance) {

// recreate block object
$block = block_instance( 'my_block_name', $instance );

// $block is now the equivalent of $this in 'normal' block
// usage, e.g.
$someconfigitem = $block->config->item2;
}
}
</code>

'my_block_name' will coincide with the name of the directory the block is stored in.

TIP: This also means that creating a block is a possible way to create code that can respond to cron with a reasonably low overhead. No actual instances of the block are required.

== 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/Appendix_A#.24this-.3Econtent| $this->content]]: "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.

Instead, Moodle expects such blocks to set two other properties when the [[Blocks/Appendix_A#get_content.28.29| 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:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
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;
}
</code>

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/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

{{Top}}

== Database support ==
In case you need to have a database table that holds some specific information that is used with your block. you will need to create a sub folder '''db''' and have an '''install.xml''' file with the table schema setup.

To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.

== See also ==
* [http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)
* A [http://cvs.moodle.org/contrib/plugins/blocks/NEWBLOCK/ NEWBLOCK template] you can all use to start you own block.

{{Moodle 2.0}}

; Moodle 2.0
* See [[Migrating contrib code to 2.0]] and [[User:Frank Ralf/Experience of converting a module to Moodle 2]] for information on relevant changes for Moodle 2.0.

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Blocks/Appendix A|''block_base'' Reference]]
* Appendix B: [[Blocks/Appendix B|Differences in the Blocks API for Moodle Versions prior to 1.5]]
* Appendix C: [[Blocks/Appendix C|Creating Database Tables for Blocks (prior to 1.7)]]

[[Category:Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック]]
[[ru:Development:Blocks]]

User:Wen Hao Chuang

2010-08-23T23:22:16Z

Chuang:

I'm one of the Moodle developers / most helpful Moodlers in the Moodle community. Currently I'm working as an "Academic Technology Consultant" at San Francisco State University (full-time), and teaches part-time in the department of Instructional Technology (ITEC).

Feel free to check out my personal website (very much outdated) at http://userwww.sfsu.edu/~wchuang

For more info about me please read my profile on moodle.org

http://moodle.org/user/view.php?id=18123&course=1

User:Wen Hao Chuang

2008-02-27T22:10:45Z

Chuang:

For more info about me please read my profile on moodle.org

http://moodle.org/user/view.php?id=18123&course=1

User talk:Wen Hao Chuang

2008-02-27T07:25:00Z

Chuang:

This is my "User talk" page. For more information about me please read my profile on moodle.org:

http://moodle.org/user/view.php?id=18123&course=5

Unit test API

2007-12-16T10:08:56Z

Chuang: /* Access to global variables */

The purpose of unit testing is to test the individual parts of the program (functions, and methods of classes) to make sure that each individually does the right thing. Once unit testing has given you the confidence that each part works, then you should use other forms of testing to ensure that the different parts work together properly.

The unit testing framework is based on the [http://www.lastcraft.com/simple_test.php SimpleTest] framework. It was incorporated into Moodle by Nick Freear and Tim Hunt from [http://www.open.ac.uk/ The Open University].

== Running the unit tests in Moodle ==

=== Running the basic tests ===

# Log in with an admin account.
# Go to the admin screen.
# Click on the '''Reports''' link near the bottom of the page.
# Click on the '''Run the unit tests''' link.
# Wait for the tests to run.

=== Options for running the tests ===

At the bottom of the tests page, there is form that lets you adjust the options used when running the tests.

==== Show passes as well as fails ====

Normally, only details of the tests that have failed are printed. Turning on this options shows details of all the passes too.

==== Show the search for test files ====

The tests to run are found automatically be searching the codebase for files whose names match '''test*.php''' in directories called '''simpletest'''. Turning on this option will print a list of the folders searched and the test files found. This is sometimes useful for debugging.

This option is particularly useful when one of your test files has a syntax error. When this happens, you sometimes just get a blank page with no error message. Turning on the show search option lets you see which test file it was that gave the error. If necessary, you can enable this option manually by adding "showsearch=1" to the end of the URL.

==== Run a thorough test (may be slow) ====

If you turn on this option, then as well as looking for files called '''test*.php''', the search also looks for files called '''slowtest*.php'''.

To be useful, the full test run should find most bugs, but not take too long to complete. So if you have very, very detailed tests of an area of the code, it may be better to select a subset for everday testing, and only use the more detailed tests when a bug is reported, or you are doing new development in that area of the code.

This option is most useful when combined with the next option.

==== Only run tests in ====

Normally, tests from all parts of the codebase are run. However, when you are just doing development of one part of the code, that is a waste of time. You can type the name of a folder (for example '''mod/quiz''') or a particular test file (for example '''lib/simpletest/testdatalib.php''') and then only those tests will be run.

[[Image:RunOnlyTheseTests.png|right]] Instead of typing a path into this box, there is an easier way. Whenever a pass or fail is displayed, the name of the test file is printed. Each section of the path name is a link to run only the tests in that folder or file.

== Writing new tests ==

As an example, suppose we wanted to start writing tests for the functions in the file 'question/editlib.php'.

=== Where to put the tests ===

If you have read the first half of this page and were paying attention, you can probably work out that you should create a folder called '''question/testeditlib''', and create a file in there called something like '''testeditlib.php'''.

The skeleton of this file should look like:

<pre><?php
/**
* Unit tests for (some of) question/editlib.php.
*
* @copyright © 2006 The Open University
* @author T.J.Hunt@open.ac.uk
* @license http://www.gnu.org/copyleft/gpl.html GNU Public License
* @package question
*/

/** */
require_once(dirname(__FILE__) . '/../../config.php');

global $CFG;
require_once($CFG->libdir . '/simpletestlib.php'); // Include the test libraries
require_once($CFG->dirroot . '/question/editlib.php'); // Include the code to test

/** This class contains the test cases for the functions in editlib.php. */
class question_editlib_test extends UnitTestCase {
function test_get_default_question_category() {
// Do the test here/
}
}
?></pre>

That is, you have a class called something_test, and in that class you have lots of methods called test_something. Normally, you have one test method for each function you want to test, and you may as well called the test method '''test_name_of_function_being_tested'''.

=== Inside a test function ===

The inside of a test function tyically looks like this:

<pre>function test_get_default_question_category() {
// Set things up in preparation for the test.

// Call the function you want to test.

// Check that the result is what you expected.
}</pre>

For example:

=== Test data ===

TODO

=== setUp and tearDown methods ===

If all your test cases relate to the same area of code, and so need the same set of test data, then you can create a method called <code>setUp()</code> that sets up the test data. If present, this method will be called before each test method. You can write a matching <code>tearDown()</code> method if there is any clean-up that needs to be done after each test case has run.

If you have some test test cases the need one sort of setup, and some other test cases that need a different setup, consider splitting your tests into two separate classes, each with its own <code>setUp()</code> method.

=== Further information ===

The simpletest documentation is at: http://simpletest.sourceforge.net/.

== Changes to your existing code to make it work with unit testing ==

When code is being tested, it gets included from inside one of the simpletest library function. If the code is expecting to be run directly (for example, if it is a view.php or index.php function), you are likely to get errors because that expectation is no longer true.

=== Include paths ===

Includes like

<pre>require_once('../../config.php'); // Won't work.</pre>

won't work. Instead, the more robust option is

<pre>require_once(dirname(__FILE__) . '/../../config.php'); // Do this.</pre>

=== Access to global variables ===

Because your code was included from within a function, you can't access global variables until you have done a global statement.

<pre>require_once(dirname(__FILE__) . '/../../config.php');
require_once($CFG->libdir . '/moodlelib.php'); // Won't work.</pre>

<pre>require_once(dirname(__FILE__) . '/../../config.php');

global $CFG; // You need this.
require_once($CFG->libdir . '/moodlelib.php'); // Will work now.</pre>

== More about unit testing in general ==

The best book I know about unit testing is '''Pragmatic Unit Testing in Java with JUnit'' by Andrew Hunt (no relation) and David Thomas. I know, this book is not called Pragmatic Unit Testing in PHP with SimpleTest. However, it is an excellent book - short, to the point, and very practical. Most of what it says is not specific to Java and JUnit and it is obvious how to apply it in our testing setup.

[[Category:Unit tests]]

Roadmap

2007-05-02T23:09:40Z

Chuang: /* Version 1.9 - Expected June 2007 */

This roadmap collects the best information about upcoming features in Moodle. It is not 100% certain - features may change according to available funding and developers.

== Version 1.9 - Expected June 2007 ==

* [[Development:Grades|Gradebook development]] - Moodle.com and OU
::The gradebook system will be revamped for performance, switching from our older "pull" model to a "push" model where all modules will now publish grades as necessary into a central table. Support for (local/state) [[Development:Outcomes|outcomes/goals/competencies]] is included! => really hope to consider including Gradebook Plus or add similar features to allow instructors to input grades directly!
* [[Development:Events|Event API]] - Moodle.com
::The new Events API provides a way for any code to "hook" into events in a clean, loosely coupled way. it's a foundation of the new Gradebook.
* [[Repository API]] ? - Open University, Moodle.com, Humboldt and Warp Networks
::Abstract all file operations to an API that allows plugins for different external repositories
* [[Development:Plan_to_Improve_Flexibility_of_Question_Category_Sharing_and_Permissions|Improved question bank]] - Jamie Pratt
::Allows questions to be shared by the whole site, a course category, a singe course, or be kept private to a single module. More control over who can do what to each question.
* [[Learning Design export]]? - Moodle.com and Open University of The Netherlands
::We plan to have a very simple export for any Moodle course into IMS LD format, as a proof of concept and to help the community start learning about IMS LD.
* [[Development:Groups_documentation_for_module_developers|New groups]] - Open University
::Site-wide groups, reusable groups, and assigning activities to groups are the major improvements being developed
* SCORM 2004?
* Integrate [[Dfwiki|nwiki]]?
* [[Development:Feedback|Integrate Feedback module]]?

== Version 2.0 - Expected Late 2007 ==

* [[IMS Learning Design]] - Moodle.com
::Support for importing/exporting LD, converting Moodle activities and sequences of activities into a standard format for sharing, and importing standard sequences into Moodle courses
* [[Conditional activities]] - Moodle.com
::Allowing dependencies and forced paths through the content
* [[Community hub]] interfaces - Moodle.com and others
::Makes it easy for users to find and navigate other systems and external Moodle repositories, leveraging the Moodle Network in various ways.
* [[Student Information API]]
::API for integrating external systems for managing student information
* Old DB install/upgrade system removed
:: The deprecated system for installing or upgrading database entries used in Moodle < 1.7 will be completely removed, while supporting only the new XML based database scheme introduced in 1.7
* [[Development:Voice|Moodle Voice]]
:: Moodle Voice is a project for embedding VoiceXML support into Moodle Core.

''Note: Moodle 2.0 will require PHP 5.1 as a minimum, because of certain improvements not available in PHP 4.''

== Version 2.1 ==

* [[Development:Portfolio API]]
::Interface Moodle activities and repositories to help produce portfolios for internal assessment AND external publication

[[Category:Developer]]
[[Category:Future]]

[[es:Planificación]]
[[fr:Planification]]

Developer documentation

2007-01-29T23:39:48Z

Chuang: /* Guidelines */

<p class="note">'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[New page name]]</nowiki></code>.<br /><br />If you are a developer, you probably want to change your [[Special:Preferences|preferences]] to include the Development namespace in searches.</p>

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

== Resources and tools ==

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

==How you can contribute==

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

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

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

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

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

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

*[[Migration to Role-driven model|Migration to Role-driven model]] @ v[[1.7]]
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]
*[[Question engine]]
*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]
*[[Authentication API]]
*[[Stats package]]
*[[Email processing]]
*[[Cookieless Sessions]]
*[[lib/formslib.php|Formslib]] for quickly writing code to display and process more accessible and secure forms.
*[[Moodle Network|Moodle Network]]

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

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

[[es:Documentación para Desarrolladores]]
[[fr:Documentation développeur]]
[[zh:开发者文档]]
[[ja:開発者ドキュメント]]