MoodleDocs - User contributions [en]

Admin settings

2013-08-22T11:42:15Z

Mattgibson: /* Individual settings */ Replaced CVS link with Github

Moodle's configuration is stored in a mixture of the config, config_plugins, and a few other tables. These settings are edited through the administration screens, which can be accessed by going to the .../admin/index.php URL on your moodle site, or using the Administration block that appears to administrators of the Moodle front page. This page explains how the code for displaying and editing of these settings works.

==Where to find the code==

This is explained further below, but in summary:
* The library code is all in lib/adminlib.php.
* The definition of the all the parts of the admin tree is in admin/settings/* some of which call out to plugins to see if they have settings they want to add.
* The editing and saving of settings is managed by admin/settings.php, admin/upgradesettings.php, and admin/search.php.
* The administration blocks that appear on the front page and on most of the admin screens is in blocks/admin_tree and blocks/admin_bookmarks.

In my experience most of this code is pretty easy to understand and work with, so here I will focus on giving an overview. For details, see the code.

==The building blocks==

All the settings are arranged into a tree structure. This tree structure is represented in memory as a tree of PHP objects.

At the root of the tree is an '''admin_root''' object.

That has children that are '''admin_category'''s.

Admin categories contain other categories, '''admin_settingpage'''s, and '''admin_externalpage'''s.

Settings pages contain individual '''admin_setting'''s.

admin_setting is a base class with lots of subclasses like '''admin_setting_configtext''', '''admin_setting_configcheckbox''', and so on. If you need to, you can create new subclasses.

External pages are for things that do not fit into the normal settings structure. For example the global assign roles page, or the page for managing activity modules.

==How the tree is built==

When Moodle needs the admin tree, it calls admin_get_root in lib/adminlib.php, which
# creates a global $ADMIN object which is an instance of admin_root.
# does require_once admin/settings/top.php, which adds the top level categories to $ADMIN.
# does require_once on all the other files in admin/settings to add more specific settings pages and the settings themselves. Some of these settings files additionally make calls out to various types of plugins. For example
#* admin/settings/plugins.php gives activity modules, blocks, question types, ... a chance to add admin settings.
# adds the admin reports to the tree.

As an optimisation, before building each bit of the tree, some capability checks are performed, and bits of the tree are skipped if the current user does not have permission to access them.

Exactly how different types of plugin should add their settings to the tree should be documented in the [[Developer_documentation#Make_a_new_plugin|instructions for writing that sort of plugin]].

==Individual settings==

Let us look at a simple example: [https://github.com/moodle/moodle/blob/master/mod/forum/settings.php mod/forum/settings.php]. This is included by admin/settings/plugins.php, which has already created $settings, which is an admin_settingpage that we can add to. The file contains lots of lines that look a bit like:

<code php>
$settings->add(new admin_setting_configcheckbox('forum_replytouser', get_string('replytouser', 'forum'),
get_string('replytouser_desc', 'forum'), 1));
</code>

What this means is that to our settings page, we are adding a checkbox setting. To understand this in more detail, we need to know what arguments the constructor for an admin_setting takes. The definition of the constructor is:

<code php>
function admin_setting($name, $visiblename, $description, $defaultsetting) {
</code>

So, $name here is 'forum_replytouser'. This means that this setting is stored in the database in the row of the config table where name='forum_replytouser', and is accessible as $CFG->forum_replytouser.

$visiblename is get_string('replytouser', 'forum'), this is the label that is put in front of setting on the admin screen.

$description is get_string('replytouser_desc', 'forum'), this is a short bit of text displayed underneath the setting to explain it further.

$defaultsetting is the default value for this setting. This value is used when Moodle is installed. For simple settings like checkboxes and text fields, this is a simple value. For some more complicated settings, this is an array.

Let as now look at a more complicated example, from mod/quiz/settingstree.php:

<code php>
$quizsettings->add(new admin_setting_text_with_advanced('quiz/timelimit',
get_string('timelimit', 'quiz'), get_string('timelimit_desc', 'quiz'),
array('value' => '0', 'fix' => false), PARAM_INT));
</code>

This shows two new things:

$name here is 'quiz/timelimit'. This is more complicated than a simple setting name. It means that this setting is stored in the config_plugins table, in the row where plugin='quiz' and name='timelimit'. It is not accessible through $CFG, to get it you can use get_config('quiz', 'timelimit').

And this example shows a $defaultsetting that is an array.

Normally, if you want a particular sort of setting, the easiest way is to look around the admin screens of your Moodle site, and find a setting like the one you want. Then go and copy the code and edit it. Therefore, we do not include a complete list of setting types here.

==External pages==

admin_externalpages represent screens of settings that do not fall into the standard pattern of admin_settings. The admin_externalpage object in the settings tree holds the URL of a PHP page that controls various settings.

In that PHP page, near the start you need to call the function admin_externalpage_setup($pagename), then, instead of the usual print_header and print_footer functions, you use admin_externalpage_print_header() and admin_externalpage_print_footer() functions. This ensures that your page appears with the administration blocks and appropriate navigation.

Note that if your external page relies on additional optional or required params, you may need to use the optional arguments to admin_externalpage_print_header to ensure that the Blocks editing on/off button works.

Note that there are some subclasses of admin_externalpage, for example admin_page_managemods. In a lot of cases, these subclasses only exist to override the search method so this page can be found by appropriate searches.

Once again, to understand this in more depth, your best approach is to look at how some of the external pages in Moodle work.

==See also==

* [[Modules|adding settings for activity modules]]
* [[Admin_reports#How_your_report_gets_included_in_the_admin_tree|adding admin reports to the tree]]
* [[Repository_plugins#APIs_for_Administration|configuration of repository plugins]]
* [[Filters#Adding_a_settings_screen|configuration for filter]]
* [[Developer_documentation|Other developer documentation]]

How to create a YUI 3 module

2013-01-13T14:30:06Z

Mattgibson: /* YUI 3 Moodle Module quick start */

{{Moodle 2.0}}This document explains how to create a YUI 3 module in Moodle.

= The two ways to write a YUI 3 module =
There is two ways to write a YUI 3 module. The two following paragraphs are sourced from a chat with Sam Hemelryk.
==The static module==
The static module is the simpler of the two, in this case you simply put your code into a module.js file within your plugin. Into that file you create a namespace and define any functions or objects you want to use.

Within PHP static modules are also pretty easy to use. The first step if to create a module definition which tells moodle what your module is called, what it requires, and can optionally give it strings.

Once the module is defined you can then use any of the several JS methods for including JS in your page and pass your module definition along.

Whilst this method is simpler to write and understand especially when you are first starting out with JavaScript it isn't as easily flexible and has some quirks that you need will need to overcome, especially with more complex JavaScript.

This method of writing a module should be used if you are just starting out with JavaScript or if the JS solution you are creating is going to be relatively simple in nature.
If you are writing something more complex I would strongly suggest looking at the other method as it will result in cleaner, easier to read code at the end of the day. However it will require you to learn your way around writing a Moodle module.

==The YUI3 Moodle Module==
This method is certainly more complex than the previous method however it is much more flexible and when you have learnt and understand what you are doing it is much quicker to write and more versatile as well. These modules can also easily include other YUI3 Moodle modules, and can choose to include module specific CSS as well.

In this method you create a '''yui''' directory within you plugin directory, and then sub directories for each module you wish to write, you name them the same as you want your module named.
Into the subdirectory you create a JavaScript file with the same name that you gave the subdirectory, e.g.'''/local/myplugin/yui/mymodule/mymodule.js'''
The JS that you then put into this file should then be written in the same way you would write a YUI module, before you ask it certainly requires a good understanding of YUI.

I would recommend this method of writing a module providing you either have an understanding of how to write a YUI module, or you are happy to learn. It normally results in cleaner easier to read code, and if desired can easily be written in such as way as to make it VERY easy to re-use in other bits of code.... particularly helpful if you have several JavaScript objects in play at a time.

= Static module quick start =
1. Create a module.js file somewhere

2. The two ways Moodle can load this file are:

a- the file is in core: declare the file into /lib/outputrequirementslib.php/find_module($component)
<code php>
//example:
case 'core_rating':
$module = array('name' => 'core_rating',
'fullpath' => '/rating/module.js',
'requires' => array('node', 'event', 'overlay', 'io', 'json'));
</code>
b- the file is in a local plugin: the first line of your module should be
<code javascript>
M.local_xxx = {
</code>
xxx being your plugin directory name.

3. Write the module.js
<code javascript>
M.local_hub={
Y : null,
transaction : [],
init : function(Y){
alert('hub module initialisation');
this.Y = Y;
},
}
</code>
4. Call this module. The best place to do this is in your renderer class (since, if a theme overrides the renderer to change the HTML, they may also need to use different JavaScript.
<code php>
$this->page->requires->js_init_call('M.local_hub.init');
You should now have loaded and called your first YUI 3 module in Moodle.
</code>
5. If you want to load your module with some other YUI modules
<code php>
$jsmodule = array(
'name' => 'local_hub',
'fullpath' => '/local/hub/module.js',
'requires' => array("overlay", "anim", "plugin")); //on this line you are loading three other YUI modules
$this->page->requires->js_init_call('M.local_hub.init',
null, false, $jsmodule);
</code>
6. If you want to pass parameter to the init function

PHP:
<code php>
$this->page->requires->js_init_call('M.local_hub.init',
array('this is the param1 value'), false, $jsmodule);
</code>
JS:
<code javascript>
init : function(Y, params){
alert(params);
....
}
</code>
7. Then you should be able to fill the module with your own YUI javascript from [http://developer.yahoo.com/yui/3/examples/ YUI examples].

= YUI 3 Moodle Module quick start =
1. Create the module_name.js file in /local/pluginname/yui/module_name/modulename.js or in /mod/modname/yui/modulename/modulename.js

2. The basic module_name.js structure is:
<code javascript>
YUI.add('moodle-local_pluginname-modulename', function(Y) {
var ModulenameNAME = 'this_is_a_module_name';
var MODULENAME = function() {
MODULENAME.superclass.constructor.apply(this, arguments);
};
Y.extend(MODULENAME, Y.Base, {
initializer : function(config) { // 'config' contains the parameter values
alert('I am in initializer');
}
}, {
NAME : ModulenameNAME, //module name is something mandatory.
// It should be in lower case without space
// as YUI use it for name space sometimes.
ATTRS : {
aparam : {}
} // Attributes are the parameters sent when the $PAGE->requires->yui_module calls the module.
// Here you can declare default values or run functions on the parameter.
// The param names must be the same as the ones declared
// in the $PAGE->requires->yui_module call.
});
M.local_pluginname = M.local_pluginname || {}; // This line use existing name path if it exists, otherwise create a new one.
// This is to avoid to overwrite previously loaded module with same name.
M.local_pluginname.init_modulename = function(config) { // 'config' contains the parameter values
alert('I am in the javascript module, Yeah!');
return new MODULENAME(config); // 'config' contains the parameter values
};
}, '@VERSION@', {
requires:['base','another_required_YUI_module', 'a_moodle_YUI_module']
});
</code>
3. Call the javascript in PHP. Again, it is best to do this in a renderer class. (if you copied the previous javascript, 2 javascript alert should appear.)
<code php>
$this->page->requires->yui_module('moodle-local_pluginname-modulename', 'M.local_pluginname.init_modulename',
array(array('aparam'=>'paramvalue')));
</code>
== Full simple example==
Once you understand and run the above quick start, here is simple YUI 3 example. It shows how to use another YUI 3 module in your module, and to use some events.
=== It includes===
* display a parameter value in two javascript alert boxes => demonstrate how to pass a param to the initialize function in two different ways
* display an overlay when you click on an image
* hide the overlay when you click on the body
* some commented code to see how Moodle YUI exception works

=== PHP ===
Create a [https://docs.moodle.org/en/Development:Local_customisation basic local plugin] (in this example it is named hub) in /local/hub/ and add this code into one of the plugin pages:
<code php>
$PAGE->requires->yui_module('moodle-local_hub-comments', 'M.local_hub.init_comments',
array(array('commentids' => '1 , 23 ,45')));
</code>

=== HTML ===
The plugin page should generate this HTML code:
<code xml>

<div id="comments"><img src='http://moodle.org/theme/moodle2/pix/moodle-logo.gif' alt='the image to click on'/></div>


<div id="commentoverlay" class="yui3-overlay-loading">
<div class="yui3-widget-hd">Comment</div>
<div class="yui3-widget-bd">this is a comment</div>
<div class="yui3-widget-bd">this is another comment</div>
</div>
</code>

=== CSS ===
The plugin style.css should contain:
<code css>
/* Hide overlay markup while loading, if js is enabled */
.yui3-js-enabled .yui3-overlay-loading {
top:-1000em;
left:-1000em;
position:absolute;
}

/* Overlay Look/Feel */
.yui3-overlay-content {
padding:3px;
border:1px solid #000;
background-color:#aaa;
}

.yui3-overlay-content .yui3-widget-hd {
padding:5px;
border:2px solid #aa0000;
background-color:#fff;
}

.yui3-overlay-content .yui3-widget-bd {
padding:5px;
border:2px solid #0000aa;
background-color:#fff;
}
</code>

=== JS ===
In /local/hub/yui/comments/comments.js
<code javascript>
YUI.add('moodle-local_hub-comments', function(Y) {

var COMMENTSNAME = 'hub_comments';

//we declare the overlay here so it's accessible to all the extended class function'
var overlay = new Y.Overlay({
srcNode:"#commentoverlay", //the main div with id = commentoverlay
width:"10em",
height:"10em",
xy:[ 0, 0],
visible: false //by default it is not displayed
});

var COMMENTS = function() {
COMMENTS.superclass.constructor.apply(this, arguments);
}

Y.extend(COMMENTS, Y.Base, {

event:null,

initializer : function(params) {

//Example how to retrieve the parameter,
//see what happens if you don't pass the parameter in the call
alert(this.get('commentids')); // You usually use an attribute because
//a attribut can have default value.
//use the ATTRS default value if not passed as parameter
alert(params.commentids); // undefined if not passed as parameter

//render the overlay
overlay.render();

// position the overlay in the middle of the web browser window
var WidgetPositionAlign = Y.WidgetPositionAlign;
overlay.set("align", {
node:"", //empty => viewport
points:[WidgetPositionAlign.CC, WidgetPositionAlign.CC]
});

//attach a show event on the div with id = comments
//we also change the div style to display the click zone
Y.one('#comments').setStyle("border", "1px solid red").on('click', this.show, this);

//uncomment the try content to see how works exception in Moodle
//this exception has been specially created for Moodle
try {
//surely_not_existing_js_function();
} catch (exception) {
new M.core.exception(exception);
}

},

show : function (e) {
overlay.show(); //show the overlay

e.halt(); // we are going to attach a new 'hide overlay' event to the body,
// because javascript always propagate event to parent tag,
// we need to tell Yahoo to stop to call the event on parent tag
// otherwise the hide event will be call right away.

//we add a new event on the body in order to hide the overlay for the next click
this.event = Y.one(document.body).on('click',this.hide,this);
},

hide : function () {
overlay.hide(); //hide the overlay
this.event.detach(); //we need to detach the hide event
//Note: it would work without but create js warning everytime
//we click on the body
}

}, {
NAME : COMMENTSNAME,
ATTRS : {
commentids: {value : 450} //default value (has no purpose in this code except to show you
// how to pass/use a param value)
}
});

M.local_hub = M.local_hub || {};
M.local_hub.init_comments = function(params) {
return new COMMENTS(params);
}

}, '@VERSION@', {
requires:['base','overlay', 'moodle-enrol-notification']
//Note: 'moodle-enrol-notification' contains Moodle YUI exception
});
</code>

==Where are my methods in the IDE?==
Some (all?) IDEs will fail to parse the above structure correctly and will not show you your methods in the structure/navigator pane. If this happens, use JSDoc format to mark the Y.extend() line as being a particular class:
<code javascript>
/**
* @class M.local_hub.init_comments
*/
Y.extend(COMMENTS, Y.Base, {
</code>
This depends to a certain extent on how you choose to instantiate your objects. The above init_widget() method can be replaced with a more class based method like a lot of the YUI library uses.

= What else to read =
Two pages are important to start with when you discover YUI 3
* you should read the [http://developer.yahoo.com/yui/3/base/ base YUI doc]. It is very useful to understand the YUI 3 Moodle module.
* you want to have a look to the [http://developer.yahoo.com/yui/3/examples/ YUI 3 examples]. Always open the examples in a window to have a look to the complete example codes.

[[Category:AJAX]]
[[Category:Javascript]]

== See Also ==
* [[Javascript and YUI 3 FAQ]]
* [[JavaScript FAQ]]

lib/formslib.php Form Definition

2012-08-17T16:02:53Z

Mattgibson: /* editor */ Added save instructions and code

{{Formslib}}
== ''definition()'' ==

The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc. is all included in a function you must define in your class.

''definition()'' is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the definition will be accepted as submitted data.

The ''definition()'' should include all elements that are going to be used on form, some elements may be removed or tweaked later in ''definition_after_data()''. Please do not create conditional elements in ''definition()'', the definition() should not directly depend on the submitted data.

Note that the definition function is called when the form class is instantiated. There is no option to (say) manipulate data in the class (that may affect the rendering of the form) between instantiating the form and calling any other methods.

<code php>
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {

function definition() {
global $CFG;

$mform =& $this->_form; // Don't forget the underscore!

$mform->addElement()... // Add elements to your form
...
} // Close the function
} // Close the class
</code>
===Passing parameters to the Form===

The constructor for ''moodleform'' allows a number of parameters including one (''$customdata'') to permit an array of arbitrary data to be passed to your form.

For example, you can pass the data "$email" and "$username" to the Form's class for use inside (say) the definition.
<code php>
...
$mform_simple = new simplehtml_form( null, array('email'=>$email, 'username'=>$username ) );
...
</code>
(the first parameter is $action, ''null'' will case the form action to be determined automatically)

Secondly, inside the form definition you can use those parameters to set the default values to some of the form's fields
<code php>
...
$mform->addElement('text', 'email', get_string('email'), 'maxlength="100" size="25" ');
$mform->setType('email', PARAM_NOTAGS);
$mform->addRule('email', get_string('missingemail'), 'required', null, 'server');
// Set default value by using a passed parameter
$mform->setDefault('email',$this->_customdata['email']);
...
</code>

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a ''legend''. <br />
('''Note''': Some themes turn off legends on admin setting pages by using CSS: <nowiki>#adminsettings legend {display:none;}</nowiki>.)

<code php>
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
</code>

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :

<code php>
$mform->closeHeaderBefore('buttonar');
</code>

==addElement==

Use the addElement method to add an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.

Some examples are below :
=== button ===

<code php>
$mform->addElement('button', 'intro', get_string("buttonlabel"));
</code>

A button element. If you want a submit or cancel button see 'submit' element.

=== checkbox ===

<code php>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</code>

This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.

You can have a 5th parameter $attributes, as on other elements.

'''BEWARE:''' Unchecked checkboxes return nothing at all (as if they didn't exist). This can surprise the unwary. You may wish to use advcheckbox instead, which does return a value when not checked. 'Advcheckbox' eliminates this problem.

==== advcheckbox ====
<code php>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));
</code>

Similar to the checkbox above, but with some important improvements:

# The (optional) 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]
#The (optional) 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.
#It returns a 0 value when unchecked. Compare with the ordinary checkbox which does not return anything at all.

=== choosecoursefile ===
{{Moodle 1.9}}
<code php>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));
</code>

Choose a file from the course files area. The fourth option is a list of options for the element.

'''Note: This has been superceded by [[#filepicker|filepicker]] in Moodle 2.'''

<code php>
array('courseid' =>null, //if it is null (default then use global $COURSE
'height' =>500, // height of the popup window
'width' =>750, // width of the popup window
'options' =>'none'); //options string for the pop up window
//eg. 'menubar=0,location=0,scrollbars,resizable'
</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('maxlength' => 255, 'size' => 48)</code>
to control the maxlength / size of the text box (note size will default to 48 if not specified)

Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the '''addGroupRule()''' method in this (complex) way:

<code php>$mform->addGroupRule('elementname', array('value' => array(array(list, of, rule, params, but, fieldname))));</code>

Where: '''"elementname"''' is the name of the choosecoursefile group element, '''"value"''' is the name of the text field within the group and the '''"list, of, addrule, params, but, fieldname"''' is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.

For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one "choosecoursefile" element, and it controls the maximum length of the field (255) with this use of addGroupRule():

<code php>$mform->addGroupRule('reference', array('value' => array(array(get_string('maximumchars', '', 255), 'maxlength', 255, 'client'))));</code>

=== date_selector ===

<code php>
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
</code>

This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'optional' => false
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

=== date_time_selector ===

<code php>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</code>

This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'step' => 5
);
</code>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===duration===
{{Moodle 2.0}}

<code php>
$mform->addElement('duration', 'timelimit', get_string('timelimit', 'quiz'));
</code>
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.

You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:
<code php>array('optional' => true)</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('size' => 5)</code>
to control the size of the text box.

=== editor ===

This replaces the old htmleditor field type. It allows the user to enter rich text content in a variety of formats.

<code php>
$mform->addElement('editor', 'fieldname', get_string('labeltext', 'langfile'));
$mform->setType('fieldname', PARAM_RAW);
</code>

If you would like to let the user use the filepicker to upload images etc. that are used in the content, then see [[Using_the_File_API_in_Moodle_forms]].

You can supply a fourth param to htmleditor of an array of options that are mostly related to file handling:

<code php>
array(
'subdirs'=>0,
'maxbytes'=>0,
'maxfiles'=>0,
'changeformat'=>0,
'context'=>null,
'noclean'=>0,
'trusttext'=>0);
</code>

To save the data if you don't care about files:
<code php>
$formdata = $mform->get_data();
$text = $formdata->fieldname['text'];
$format = $formdata->fieldname['format'];
</code>

=== file ===

File upload input box with browse button. In the form definition type

<code php>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</code>

after form submission and validation use

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</code>

If there is no requirement to save the file, you can read the file contents directly into a string as follows...

<code php>
$mform->get_file_content('attachment');
</code>

If you need advanced settings such as required file, different max upload size or name of uploaded file

<code php>
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->addRule('attachment', null, 'required');

</code>

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
</code>

When porting old code it is also possible to use the upload manager directly for processing of uploaded files.

Please note that if using set_upload_manager() it must be before addElement('file',..).

{{Moodle 2.0}}
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.

===filepicker===
{{Moodle 2.0}}
General replacement of ''file'' element.

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>
See also [[Using the File API in Moodle forms]]

=== hidden ===
<code php>
$mform->addElement('hidden', 'reply', 'yes');
</code>

A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').

=== html ===
You can add arbitrary HTML to your Moodle form:

<code php>
$mform->addElement('html', '<div class="qheader">');
</code>

See [http://moodle.org/mod/forum/discuss.php?d=126935 "Question: Can I put a moodleform inside a table td?"] for a concrete example.

=== htmleditor & format ===

These elements are now deprecated. Please use the [[#editor|editor]] field type instead.

===modgrade===
<pre>
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
</pre>
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.

A helpbutton is automatically added.

===modvisible===
<pre>
$mform->addElement('modvisible', 'visible', get_string('visible'));
</pre>
This is a custom element for selecting a grade visibility in an activity mod update form.

===password===
<pre>
$mform->addElement('password', 'password', get_string('label'), $attributes);
</pre>

A password element. Fourth param is an array or string of attributes.

===passwordunmask===
{{Moodle 1.9}}
<pre>
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
</pre>

A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.

=== radio ===
{{Moodle 2.3}}
<code php>
$radioarray=array();
$radioarray[] =& $mform->createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] =& $mform->createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</code>

Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.

It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.

Since 2.3 it cannot be statically called anymore, so we need to call createElement from $mform reference.

==== setDefault ====

To set the default for a radio button group as above use the following :

<code php>
$mform->setDefault('yesno', 0);
</code>

This would make the default 'no'.

===select===
<pre>
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
</pre>

The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.

It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].

====multi-select====
<pre>
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);
$select->setMultiple(true);
</pre>

=====setSelected=====

To set the default selected item in a select element, you should use the 'setSelected' function, as follows:
<code>
$select = &$mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);
$select->setSelected('blue');
</code>
However you probably don't want to do this. Instead you probably want to use setDefault, or set it using the form's setData method.

===selectyesno===
<pre>
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
</pre>

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

===selectwithlink===
<pre>
$options = array();
$mform->addElement('selectwithlink', 'scaleid', get_string('scale'), $options, null,
array('link' => $CFG->wwwroot.'/grade/edit/scale/edit.php?courseid='.$COURSE->id, 'label' => get_string('scalescustomcreate')));
</pre>
select type element with options containing link
===static===
<pre>
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));
</pre>

This is a static element. It should be used with care if it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.

===submit, reset and cancel===

<pre>
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = &$mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
$mform->closeHeaderBefore('buttonar');
</pre>

A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.

You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges'). Note the '''$this''' not '''$mform'''

<pre>
$this->add_action_buttons();
</pre>

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :
<pre>
$attributes='size="20"';
$attributes=array('size'=>'20');
</pre>

Generally you are encouraged to use CSS instead of using attributes for styling.

A format element can be used as a format select box. It will be non-selectable if you're using an html editor.

The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.

===textarea===

<pre>
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
</pre>

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

===recaptcha===
{{Moodle 1.9}}
<pre>
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);
</pre>

Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.

To check whether recaptcha is enabled at site level use:
<pre>
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {
//recaptcha is enabled
}
</pre>

===tags===
{{Moodle 2.0}}

<pre>
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);
</pre>

Used for editing a list of tags, for example on a blog post.

There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.

The value should be set/returned as an array of tags.

===grading===
<code php>
$mform->addElement('grading', 'advancedgrading', get_string('grade').':', array('gradinginstance' => $gradinginstance));
</code>

Custom element for advanced grading plugins.

When adding the 'grading' element to the form, developer must pass an object of class gradingform_instance as $attributes['gradinginstance']. Otherwise an exception will be thrown.

===questioncategory===
<code php>
$mform->addElement('questioncategory', 'category', get_string('category', 'question'),
array('contexts'=>$contexts, 'top'=>true, 'currentcat'=>$currentcat, 'nochildrenof'=>$currentcat));
</code>
Creates a drop down element to select a question category.

Options are:
'''contexts''' - (required) context in which question appears
'''currentcat''' - (optional) course category
'''top''' - (optional) if true will put top categories on top
'''nochildrenof''' - (optional) Format categories into an indented list reflecting the tree structure

==addGroup==

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

<pre>
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
</pre>

You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).

Here's a bad example (don't do this for real, use the 'optional' => true option of the date element): putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:

<pre>
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');
</pre>

==addRule==
<pre>
$mform->addRule('elementname', get_string('error'), 'rule type', 'extraruledata', 'server'(default), false, false);
</pre>

The first param(element) is an element name and second(message) is the error message that will be displayed to the user.
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.

<pre>
* @param string $element Form element name
* @param string $message Message to display for invalid data
* @param string $type Rule type, use getRegisteredRules() to get types
* @param string $format (optional)Required for extra rule data
* @param string $validation (optional)Where to perform validation: "server", "client"
* @param boolean $reset Client-side validation: reset the form element to its original value if there is an error?
* @param boolean $force Force the rule to be applied, even if the target form element does not exist
</pre>

'''Common Rule Types'''
* required
* maxlength
* minlength
* rangelength
* email
* regex
* lettersonly
* alphanumeric
* numeric
* nopunctuation
* nonzero
* callback
* compare

===Server side and Client side===
In case you use the ''Client side'' validation option, you can mainly check for an empty or not input field. unless you write some ''Client side'' code which will probably be JavaScript functions to verify the data inside the input fields before it is submitted to the server. It could save some time if those functions are short, simple and quick to compute.
In case you need a more complex validation checks which relay on Moodle's internal PHP libraries (or other/external PHP libraries) you better use the ''Server side'' validation checks. Where you can query the DB, write complex PHP validation functions and much much more, that are not available (easily) when using JavaScript on the client's side.

==setHelpButton==
{{Moodle 1.9}}

<pre>
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));
</pre>
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :

<pre>
* @param string $page The keyword that defines a help page
* @param string $title The title of links, rollover tips, alt tags etc
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.
* @param string $module Which module is the page defined in
* @param mixed $image Use a help image for the link? (true/false/"both")
* @param boolean $linktext If true, display the title next to the help icon.
* @param string $text If defined then this text is used in the page, and
* the $page variable is ignored.
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif
</pre>
Make sure you don't set boolean $return to false.

You need to do use this method after addElement();

==addHelpButton==
{{Moodle 2.0}}

<code php>
$mform->addHelpButton('api_key_field', 'api_key', 'block_extsearch');
</code>

In Moodle 2.0 the "setHelpButton" method has been deprecated in favor of the "addHelpButton" method, which has a simplified interface and uses $OUTPUT->help_icon() on the back end. The following parameters are expected:

<code php>
/**
* @param $elementname The name of the form element to add the help button for
* @param $identifier The identifier for the help string and its title (see below)
* @param $component The component name to look for the help string in
*/
</code>
Unlike in Moodle 1.9, it is no longer necessary to put your help pages in separate HTML files. Instead, the function looks for two strings:

# get_string($identifier, $component) // The title of the help page
# get_string("{$identifier}_help", $component) // The content of the help page

So you will need to have '''$identifier''' and '''{$identifier}_help''' defined in order for the help button to be created properly. For example the multiple choice question editing form has a button for shuffling the answers.
<code php>
$mform->addHelpButton('shuffleanswers', 'shuffleanswers', 'qtype_multichoice');
</code>
and so the language file includes the strings
<code php>
$string['shuffleanswers'] = 'Shuffle the choices?';
$string['shuffleanswers_help'] = 'If enabled,.....';
</code>
You can also add the language string like
<code php>
$string['shuffleanswers_link'] = 'question/shuffleanswers';
</code>
to add a link to more help on Moodle docs. See [[String_API]] for more information about help icons.

==setDefault==

<pre>
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
</pre>

Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.

==disabledIf==

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value='1')

* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the second argument in addElement or addGroup.
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.
* $condition will be 'notchecked', 'checked', 'noitemselected', 'eq' or, if it is anything else, we test for 'neq'.
** If $condition is 'eq' or 'neq' then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
** If $condition is 'checked' or 'notchecked' then we check to see if a checkbox is checked or not.
** If $condition is 'noitemselected' then we check to see whether nothing is selected in a dropdown list.

Examples:
// Disable my control unless a checkbox is checked.
$mform->disabledIf('mycontrol', 'somecheckbox');

// Disable my control if a checkbox '''is''' checked.
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');

// Disable my control when a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);

// Disable my control unless a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'neq', 42);

The possible choices here are in the dependency manager in lib/form/form.js.

==setType==

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

===Most Commonly Used PARAM_* Types===

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

* PARAM_CLEAN is deprecated and you should try to use a more specific type.
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
* PARAM_INT should be used for integers.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

==References==

* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]

[[Category:Formslib]]
[[Category:Interfaces]]

If you have problems creating php forms you may get them with form builder http://phpforms.net/tutorial/html-basics/form-builder.html

How to create a YUI 3 module

2012-06-25T11:09:08Z

Mattgibson: /* Where are my methods in the IDE? */

{{Moodle 2.0}}This document explains how to create a YUI 3 module in Moodle.

= The two ways to write a YUI 3 module =
There is two ways to write a YUI 3 module. The two following paragraphs are sourced from a chat with Sam Hemelryk.
==The static module==
The static module is the simpler of the two, in this case you simply put your code into a module.js file within your plugin. Into that file you create a namespace and define any functions or objects you want to use.

Within PHP static modules are also pretty easy to use. The first step if to create a module definition which tells moodle what your module is called, what it requires, and can optionally give it strings.

Once the module is defined you can then use any of the several JS methods for including JS in your page and pass your module definition along.

Whilst this method is simpler to write and understand especially when you are first starting out with JavaScript it isn't as easily flexible and has some quirks that you need will need to overcome, especially with more complex JavaScript.

This method of writing a module should be used if you are just starting out with JavaScript or if the JS solution you are creating is going to be relatively simple in nature.
If you are writing something more complex I would strongly suggest looking at the other method as it will result in cleaner, easier to read code at the end of the day. However it will require you to learn your way around writing a Moodle module.

==The YUI3 Moodle Module==
This method is certainly more complex than the previous method however it is much more flexible and when you have learnt and understand what you are doing it is much quicker to write and more versatile as well. These modules can also easily include other YUI3 Moodle modules, and can choose to include module specific CSS as well.

In this method you create a '''yui''' directory within you plugin directory, and then sub directories for each module you wish to write, you name them the same as you want your module named.
Into the subdirectory you create a JavaScript file with the same name that you gave the subdirectory, e.g.'''/local/myplugin/yui/mymodule/mymodule.js'''
The JS that you then put into this file should then be written in the same way you would write a YUI module, before you ask it certainly requires a good understanding of YUI.

I would recommend this method of writing a module providing you either have an understanding of how to write a YUI module, or you are happy to learn. It normally results in cleaner easier to read code, and if desired can easily be written in such as way as to make it VERY easy to re-use in other bits of code.... particularly helpful if you have several JavaScript objects in play at a time.

= Static module quick start =
1. Create a module.js file somewhere

2. The two ways Moodle can load this file are:

a- the file is in core: declare the file into /lib/outputrequirementslib.php/find_module($component)
<code php>
//example:
case 'core_rating':
$module = array('name' => 'core_rating',
'fullpath' => '/rating/module.js',
'requires' => array('node', 'event', 'overlay', 'io', 'json'));
</code>
b- the file is in a local plugin: the first line of your module should be
<code javascript>
M.local_xxx = {
</code>
xxx being your plugin directory name.

3. Write the module.js
<code javascript>
M.local_hub={
Y : null,
transaction : [],
init : function(Y){
alert('hub module initialisation');
this.Y = Y;
},
}
</code>
4. Call this module. The best place to do this is in your renderer class (since, if a theme overrides the renderer to change the HTML, they may also need to use different JavaScript.
<code php>
$this->page->requires->js_init_call('M.local_hub.init');
You should now have loaded and called your first YUI 3 module in Moodle.
</code>
5. If you want to load your module with some other YUI modules
<code php>
$jsmodule = array(
'name' => 'local_hub',
'fullpath' => '/local/hub/module.js',
'requires' => array("overlay", "anim", "plugin")); //on this line you are loading three other YUI modules
$this->page->requires->js_init_call('M.local_hub.init',
null, false, $jsmodule);
</code>
6. If you want to pass parameter to the init function

PHP:
<code php>
$this->page->requires->js_init_call('M.local_hub.init',
array('this is the param1 value'), false, $jsmodule);
</code>
JS:
<code javascript>
init : function(Y, params){
alert(params);
....
}
</code>
7. Then you should be able to fill the module with your own YUI javascript from [http://developer.yahoo.com/yui/3/examples/ YUI examples].

= YUI 3 Moodle Module quick start =
1. Create the module_name.js file in /local/pluginname/yui/module_name/modulename.js or in /mod/modname/yui/modulename/modulename.js

2. The basic module_name.js structure is:
<code javascript>
YUI.add('moodle-local_pluginname-modulename', function(Y) {
var ModulenameNAME = 'this_is_a_module_name';
var MODULENAME = function() {
MODULENAME.superclass.constructor.apply(this, arguments);
};
Y.extend(MODULENAME, Y.Base, {
initializer : function(config) { // 'config' contains the parameter values
alert('I am in initializer');
}
}, {
NAME : ModulenameNAME, //module name is something mandatory.
// It should be in lower case without space
// as YUI use it for name space sometimes.
ATTRS : {
aparam : {}
} // Attributes are the parameters sent when the $PAGE->requires->yui_module calls the module.
// Here you can declare default values or run functions on the parameter.
// The param names must be the same as the ones declared
// in the $PAGE->requires->yui_module call.
});
M.local_pluginname = M.local_pluginname || {}; // This line use existing name path if it exists, ortherwise create a new one.
// This is to avoid to overwrite previously loaded module with same name.
M.local_pluginname.init_modulename = function(config) { // 'config' contains the parameter values
alert('I am in the javascript module, Yeah!');
return new MODULENAME(config); // 'config' contains the parameter values
}
}, '@VERSION@', {
requires:['base','another_required_YUI_module', 'a_moodle_YUI_module']
});
</code>
3. Call the javascript in PHP. Again, it is best to do this in a renderer class. (if you copied the previous javascript, 2 javascript alert should appear.)
<code php>
$this->page->requires->yui_module('moodle-local_pluginname-modulename', 'M.local_pluginname.init_modulename',
array(array('aparam'=>'paramvalue')));
</code>
== Full simple example==
Once you understand and run the above quick start, here is simple YUI 3 example. It shows how to use another YUI 3 module in your module, and to use some events.
=== It includes===
* display a parameter value in two javascript alert boxes => demonstrate how to pass a param to the initialize function in two different ways
* display an overlay when you click on an image
* hide the overlay when you click on the body
* some commented code to see how Moodle YUI exception works

=== PHP ===
Create a [https://docs.moodle.org/en/Development:Local_customisation basic local plugin] (in this example it is named hub) in /local/hub/ and add this code into one of the plugin pages:
<code php>
$PAGE->requires->yui_module('moodle-local_hub-comments', 'M.local_hub.init_comments',
array(array('commentids' => '1 , 23 ,45')));
</code>

=== HTML ===
The plugin page should generate this HTML code:
<code xml>

<div id="comments"><img src='http://moodle.org/theme/moodle2/pix/moodle-logo.gif' alt='the image to click on'/></div>


<div id="commentoverlay" class="yui3-overlay-loading">
<div class="yui3-widget-hd">Comment</div>
<div class="yui3-widget-bd">this is a comment</div>
<div class="yui3-widget-bd">this is another comment</div>
</div>
</code>

=== CSS ===
The plugin style.css should contain:
<code css>
/* Hide overlay markup while loading, if js is enabled */
.yui3-js-enabled .yui3-overlay-loading {
top:-1000em;
left:-1000em;
position:absolute;
}

/* Overlay Look/Feel */
.yui3-overlay-content {
padding:3px;
border:1px solid #000;
background-color:#aaa;
}

.yui3-overlay-content .yui3-widget-hd {
padding:5px;
border:2px solid #aa0000;
background-color:#fff;
}

.yui3-overlay-content .yui3-widget-bd {
padding:5px;
border:2px solid #0000aa;
background-color:#fff;
}
</code>

=== JS ===
In /local/hub/yui/comments/comments.js
<code javascript>
YUI.add('moodle-local_hub-comments', function(Y) {

var COMMENTSNAME = 'hub_comments';

//we declare the overlay here so it's accessible to all the extended class function'
var overlay = new Y.Overlay({
srcNode:"#commentoverlay", //the main div with id = commentoverlay
width:"10em",
height:"10em",
xy:[ 0, 0],
visible: false //by default it is not displayed
});

var COMMENTS = function() {
COMMENTS.superclass.constructor.apply(this, arguments);
}

Y.extend(COMMENTS, Y.Base, {

event:null,

initializer : function(params) {

//Example how to retrieve the parameter,
//see what happens if you don't pass the parameter in the call
alert(this.get('commentids')); // You usually use an attribute because
//a attribut can have default value.
//use the ATTRS default value if not passed as parameter
alert(params.commentids); // undefined if not passed as parameter

//render the overlay
overlay.render();

// position the overlay in the middle of the web browser window
var WidgetPositionAlign = Y.WidgetPositionAlign;
overlay.set("align", {
node:"", //empty => viewport
points:[WidgetPositionAlign.CC, WidgetPositionAlign.CC]
});

//attach a show event on the div with id = comments
//we also change the div style to display the click zone
Y.one('#comments').setStyle("border", "1px solid red").on('click', this.show, this);

//uncomment the try content to see how works exception in Moodle
//this exception has been specially created for Moodle
try {
//surely_not_existing_js_function();
} catch (exception) {
new M.core.exception(exception);
}

},

show : function (e) {
overlay.show(); //show the overlay

e.halt(); // we are going to attach a new 'hide overlay' event to the body,
// because javascript always propagate event to parent tag,
// we need to tell Yahoo to stop to call the event on parent tag
// otherwise the hide event will be call right away.

//we add a new event on the body in order to hide the overlay for the next click
this.event = Y.one(document.body).on('click',this.hide,this);
},

hide : function () {
overlay.hide(); //hide the overlay
this.event.detach(); //we need to detach the hide event
//Note: it would work without but create js warning everytime
//we click on the body
}

}, {
NAME : COMMENTSNAME,
ATTRS : {
commentids: {value : 450} //default value (has no purpose in this code except to show you
// how to pass/use a param value)
}
});

M.local_hub = M.local_hub || {};
M.local_hub.init_comments = function(params) {
return new COMMENTS(params);
}

}, '@VERSION@', {
requires:['base','overlay', 'moodle-enrol-notification']
//Note: 'moodle-enrol-notification' contains Moodle YUI exception
});
</code>

==Where are my methods in the IDE?==
Some (all?) IDEs will fail to parse the above structure correctly and will not show you your methods in the structure/navigator pane. If this happens, use JSDoc format to mark the Y.extend() line as being a particular class:
<code javascript>
/**
* @class M.local_hub.init_comments
*/
Y.extend(COMMENTS, Y.Base, {
</code>
This depends to a certain extent on how you choose to instantiate your objects. The above init_widget() method can be replaced with a more class based method like a lot of the YUI library uses.

= What else to read =
Two pages are important to start with when you discover YUI 3
* you should read the [http://developer.yahoo.com/yui/3/base/ base YUI doc]. It is very useful to understand the YUI 3 Moodle module.
* you want to have a look to the [http://developer.yahoo.com/yui/3/examples/ YUI 3 examples]. Always open the examples in a window to have a look to the complete example codes.

[[Category:AJAX]]
[[Category:Javascript]]

== See Also ==
* [[Javascript and YUI 3 FAQ]]
* [[JavaScript FAQ]]

How to create a YUI 3 module

2012-06-25T11:02:36Z

Mattgibson: /* Where are my methods in the IDE? */

{{Moodle 2.0}}This document explains how to create a YUI 3 module in Moodle.

= The two ways to write a YUI 3 module =
There is two ways to write a YUI 3 module. The two following paragraphs are sourced from a chat with Sam Hemelryk.
==The static module==
The static module is the simpler of the two, in this case you simply put your code into a module.js file within your plugin. Into that file you create a namespace and define any functions or objects you want to use.

Within PHP static modules are also pretty easy to use. The first step if to create a module definition which tells moodle what your module is called, what it requires, and can optionally give it strings.

Once the module is defined you can then use any of the several JS methods for including JS in your page and pass your module definition along.

Whilst this method is simpler to write and understand especially when you are first starting out with JavaScript it isn't as easily flexible and has some quirks that you need will need to overcome, especially with more complex JavaScript.

This method of writing a module should be used if you are just starting out with JavaScript or if the JS solution you are creating is going to be relatively simple in nature.
If you are writing something more complex I would strongly suggest looking at the other method as it will result in cleaner, easier to read code at the end of the day. However it will require you to learn your way around writing a Moodle module.

==The YUI3 Moodle Module==
This method is certainly more complex than the previous method however it is much more flexible and when you have learnt and understand what you are doing it is much quicker to write and more versatile as well. These modules can also easily include other YUI3 Moodle modules, and can choose to include module specific CSS as well.

In this method you create a '''yui''' directory within you plugin directory, and then sub directories for each module you wish to write, you name them the same as you want your module named.
Into the subdirectory you create a JavaScript file with the same name that you gave the subdirectory, e.g.'''/local/myplugin/yui/mymodule/mymodule.js'''
The JS that you then put into this file should then be written in the same way you would write a YUI module, before you ask it certainly requires a good understanding of YUI.

I would recommend this method of writing a module providing you either have an understanding of how to write a YUI module, or you are happy to learn. It normally results in cleaner easier to read code, and if desired can easily be written in such as way as to make it VERY easy to re-use in other bits of code.... particularly helpful if you have several JavaScript objects in play at a time.

= Static module quick start =
1. Create a module.js file somewhere

2. The two ways Moodle can load this file are:

a- the file is in core: declare the file into /lib/outputrequirementslib.php/find_module($component)
<code php>
//example:
case 'core_rating':
$module = array('name' => 'core_rating',
'fullpath' => '/rating/module.js',
'requires' => array('node', 'event', 'overlay', 'io', 'json'));
</code>
b- the file is in a local plugin: the first line of your module should be
<code javascript>
M.local_xxx = {
</code>
xxx being your plugin directory name.

3. Write the module.js
<code javascript>
M.local_hub={
Y : null,
transaction : [],
init : function(Y){
alert('hub module initialisation');
this.Y = Y;
},
}
</code>
4. Call this module. The best place to do this is in your renderer class (since, if a theme overrides the renderer to change the HTML, they may also need to use different JavaScript.
<code php>
$this->page->requires->js_init_call('M.local_hub.init');
You should now have loaded and called your first YUI 3 module in Moodle.
</code>
5. If you want to load your module with some other YUI modules
<code php>
$jsmodule = array(
'name' => 'local_hub',
'fullpath' => '/local/hub/module.js',
'requires' => array("overlay", "anim", "plugin")); //on this line you are loading three other YUI modules
$this->page->requires->js_init_call('M.local_hub.init',
null, false, $jsmodule);
</code>
6. If you want to pass parameter to the init function

PHP:
<code php>
$this->page->requires->js_init_call('M.local_hub.init',
array('this is the param1 value'), false, $jsmodule);
</code>
JS:
<code javascript>
init : function(Y, params){
alert(params);
....
}
</code>
7. Then you should be able to fill the module with your own YUI javascript from [http://developer.yahoo.com/yui/3/examples/ YUI examples].

= YUI 3 Moodle Module quick start =
1. Create the module_name.js file in /local/pluginname/yui/module_name/modulename.js or in /mod/modname/yui/modulename/modulename.js

2. The basic module_name.js structure is:
<code javascript>
YUI.add('moodle-local_pluginname-modulename', function(Y) {
var ModulenameNAME = 'this_is_a_module_name';
var MODULENAME = function() {
MODULENAME.superclass.constructor.apply(this, arguments);
};
Y.extend(MODULENAME, Y.Base, {
initializer : function(config) { // 'config' contains the parameter values
alert('I am in initializer');
}
}, {
NAME : ModulenameNAME, //module name is something mandatory.
// It should be in lower case without space
// as YUI use it for name space sometimes.
ATTRS : {
aparam : {}
} // Attributes are the parameters sent when the $PAGE->requires->yui_module calls the module.
// Here you can declare default values or run functions on the parameter.
// The param names must be the same as the ones declared
// in the $PAGE->requires->yui_module call.
});
M.local_pluginname = M.local_pluginname || {}; // This line use existing name path if it exists, ortherwise create a new one.
// This is to avoid to overwrite previously loaded module with same name.
M.local_pluginname.init_modulename = function(config) { // 'config' contains the parameter values
alert('I am in the javascript module, Yeah!');
return new MODULENAME(config); // 'config' contains the parameter values
}
}, '@VERSION@', {
requires:['base','another_required_YUI_module', 'a_moodle_YUI_module']
});
</code>
3. Call the javascript in PHP. Again, it is best to do this in a renderer class. (if you copied the previous javascript, 2 javascript alert should appear.)
<code php>
$this->page->requires->yui_module('moodle-local_pluginname-modulename', 'M.local_pluginname.init_modulename',
array(array('aparam'=>'paramvalue')));
</code>
== Full simple example==
Once you understand and run the above quick start, here is simple YUI 3 example. It shows how to use another YUI 3 module in your module, and to use some events.
=== It includes===
* display a parameter value in two javascript alert boxes => demonstrate how to pass a param to the initialize function in two different ways
* display an overlay when you click on an image
* hide the overlay when you click on the body
* some commented code to see how Moodle YUI exception works

=== PHP ===
Create a [https://docs.moodle.org/en/Development:Local_customisation basic local plugin] (in this example it is named hub) in /local/hub/ and add this code into one of the plugin pages:
<code php>
$PAGE->requires->yui_module('moodle-local_hub-comments', 'M.local_hub.init_comments',
array(array('commentids' => '1 , 23 ,45')));
</code>

=== HTML ===
The plugin page should generate this HTML code:
<code xml>

<div id="comments"><img src='http://moodle.org/theme/moodle2/pix/moodle-logo.gif' alt='the image to click on'/></div>


<div id="commentoverlay" class="yui3-overlay-loading">
<div class="yui3-widget-hd">Comment</div>
<div class="yui3-widget-bd">this is a comment</div>
<div class="yui3-widget-bd">this is another comment</div>
</div>
</code>

=== CSS ===
The plugin style.css should contain:
<code css>
/* Hide overlay markup while loading, if js is enabled */
.yui3-js-enabled .yui3-overlay-loading {
top:-1000em;
left:-1000em;
position:absolute;
}

/* Overlay Look/Feel */
.yui3-overlay-content {
padding:3px;
border:1px solid #000;
background-color:#aaa;
}

.yui3-overlay-content .yui3-widget-hd {
padding:5px;
border:2px solid #aa0000;
background-color:#fff;
}

.yui3-overlay-content .yui3-widget-bd {
padding:5px;
border:2px solid #0000aa;
background-color:#fff;
}
</code>

=== JS ===
In /local/hub/yui/comments/comments.js
<code javascript>
YUI.add('moodle-local_hub-comments', function(Y) {

var COMMENTSNAME = 'hub_comments';

//we declare the overlay here so it's accessible to all the extended class function'
var overlay = new Y.Overlay({
srcNode:"#commentoverlay", //the main div with id = commentoverlay
width:"10em",
height:"10em",
xy:[ 0, 0],
visible: false //by default it is not displayed
});

var COMMENTS = function() {
COMMENTS.superclass.constructor.apply(this, arguments);
}

Y.extend(COMMENTS, Y.Base, {

event:null,

initializer : function(params) {

//Example how to retrieve the parameter,
//see what happens if you don't pass the parameter in the call
alert(this.get('commentids')); // You usually use an attribute because
//a attribut can have default value.
//use the ATTRS default value if not passed as parameter
alert(params.commentids); // undefined if not passed as parameter

//render the overlay
overlay.render();

// position the overlay in the middle of the web browser window
var WidgetPositionAlign = Y.WidgetPositionAlign;
overlay.set("align", {
node:"", //empty => viewport
points:[WidgetPositionAlign.CC, WidgetPositionAlign.CC]
});

//attach a show event on the div with id = comments
//we also change the div style to display the click zone
Y.one('#comments').setStyle("border", "1px solid red").on('click', this.show, this);

//uncomment the try content to see how works exception in Moodle
//this exception has been specially created for Moodle
try {
//surely_not_existing_js_function();
} catch (exception) {
new M.core.exception(exception);
}

},

show : function (e) {
overlay.show(); //show the overlay

e.halt(); // we are going to attach a new 'hide overlay' event to the body,
// because javascript always propagate event to parent tag,
// we need to tell Yahoo to stop to call the event on parent tag
// otherwise the hide event will be call right away.

//we add a new event on the body in order to hide the overlay for the next click
this.event = Y.one(document.body).on('click',this.hide,this);
},

hide : function () {
overlay.hide(); //hide the overlay
this.event.detach(); //we need to detach the hide event
//Note: it would work without but create js warning everytime
//we click on the body
}

}, {
NAME : COMMENTSNAME,
ATTRS : {
commentids: {value : 450} //default value (has no purpose in this code except to show you
// how to pass/use a param value)
}
});

M.local_hub = M.local_hub || {};
M.local_hub.init_comments = function(params) {
return new COMMENTS(params);
}

}, '@VERSION@', {
requires:['base','overlay', 'moodle-enrol-notification']
//Note: 'moodle-enrol-notification' contains Moodle YUI exception
});
</code>

==Where are my methods in the IDE?==
Some (all?) IDEs will fail to parse the above structure correctly and will not show you your methods in the structure/navigator pane. If this happens, use JSDoc format to mark the Y.extend() line as being a particular class:
<code javascript>
/**
* @class M.local_hub.init_comments
*/
Y.extend(COMMENTS, Y.Base, {
</code>
This depends to a certain extent on how you choose to instantiate your objects. The above init_widget() method can be replaced with a more class based method like a lot of the YUI library uses.

= What else to read =
Two pages are important to start with when you discover YUI 3
* you should read the [http://developer.yahoo.com/yui/3/base/ base YUI doc]. It is very useful to understand the YUI 3 Moodle module.
* you want to have a look to the [http://developer.yahoo.com/yui/3/examples/ YUI 3 examples]. Always open the examples in a window to have a look to the complete example codes.

[[Category:AJAX]]
[[Category:Javascript]]

== See Also ==
* [[Javascript and YUI 3 FAQ]]
* [[JavaScript FAQ]]

How to create a YUI 3 module

2012-06-25T11:02:13Z

Mattgibson: /* Full simple example */

{{Moodle 2.0}}This document explains how to create a YUI 3 module in Moodle.

= The two ways to write a YUI 3 module =
There is two ways to write a YUI 3 module. The two following paragraphs are sourced from a chat with Sam Hemelryk.
==The static module==
The static module is the simpler of the two, in this case you simply put your code into a module.js file within your plugin. Into that file you create a namespace and define any functions or objects you want to use.

Within PHP static modules are also pretty easy to use. The first step if to create a module definition which tells moodle what your module is called, what it requires, and can optionally give it strings.

Once the module is defined you can then use any of the several JS methods for including JS in your page and pass your module definition along.

Whilst this method is simpler to write and understand especially when you are first starting out with JavaScript it isn't as easily flexible and has some quirks that you need will need to overcome, especially with more complex JavaScript.

This method of writing a module should be used if you are just starting out with JavaScript or if the JS solution you are creating is going to be relatively simple in nature.
If you are writing something more complex I would strongly suggest looking at the other method as it will result in cleaner, easier to read code at the end of the day. However it will require you to learn your way around writing a Moodle module.

==The YUI3 Moodle Module==
This method is certainly more complex than the previous method however it is much more flexible and when you have learnt and understand what you are doing it is much quicker to write and more versatile as well. These modules can also easily include other YUI3 Moodle modules, and can choose to include module specific CSS as well.

In this method you create a '''yui''' directory within you plugin directory, and then sub directories for each module you wish to write, you name them the same as you want your module named.
Into the subdirectory you create a JavaScript file with the same name that you gave the subdirectory, e.g.'''/local/myplugin/yui/mymodule/mymodule.js'''
The JS that you then put into this file should then be written in the same way you would write a YUI module, before you ask it certainly requires a good understanding of YUI.

I would recommend this method of writing a module providing you either have an understanding of how to write a YUI module, or you are happy to learn. It normally results in cleaner easier to read code, and if desired can easily be written in such as way as to make it VERY easy to re-use in other bits of code.... particularly helpful if you have several JavaScript objects in play at a time.

= Static module quick start =
1. Create a module.js file somewhere

2. The two ways Moodle can load this file are:

a- the file is in core: declare the file into /lib/outputrequirementslib.php/find_module($component)
<code php>
//example:
case 'core_rating':
$module = array('name' => 'core_rating',
'fullpath' => '/rating/module.js',
'requires' => array('node', 'event', 'overlay', 'io', 'json'));
</code>
b- the file is in a local plugin: the first line of your module should be
<code javascript>
M.local_xxx = {
</code>
xxx being your plugin directory name.

3. Write the module.js
<code javascript>
M.local_hub={
Y : null,
transaction : [],
init : function(Y){
alert('hub module initialisation');
this.Y = Y;
},
}
</code>
4. Call this module. The best place to do this is in your renderer class (since, if a theme overrides the renderer to change the HTML, they may also need to use different JavaScript.
<code php>
$this->page->requires->js_init_call('M.local_hub.init');
You should now have loaded and called your first YUI 3 module in Moodle.
</code>
5. If you want to load your module with some other YUI modules
<code php>
$jsmodule = array(
'name' => 'local_hub',
'fullpath' => '/local/hub/module.js',
'requires' => array("overlay", "anim", "plugin")); //on this line you are loading three other YUI modules
$this->page->requires->js_init_call('M.local_hub.init',
null, false, $jsmodule);
</code>
6. If you want to pass parameter to the init function

PHP:
<code php>
$this->page->requires->js_init_call('M.local_hub.init',
array('this is the param1 value'), false, $jsmodule);
</code>
JS:
<code javascript>
init : function(Y, params){
alert(params);
....
}
</code>
7. Then you should be able to fill the module with your own YUI javascript from [http://developer.yahoo.com/yui/3/examples/ YUI examples].

= YUI 3 Moodle Module quick start =
1. Create the module_name.js file in /local/pluginname/yui/module_name/modulename.js or in /mod/modname/yui/modulename/modulename.js

2. The basic module_name.js structure is:
<code javascript>
YUI.add('moodle-local_pluginname-modulename', function(Y) {
var ModulenameNAME = 'this_is_a_module_name';
var MODULENAME = function() {
MODULENAME.superclass.constructor.apply(this, arguments);
};
Y.extend(MODULENAME, Y.Base, {
initializer : function(config) { // 'config' contains the parameter values
alert('I am in initializer');
}
}, {
NAME : ModulenameNAME, //module name is something mandatory.
// It should be in lower case without space
// as YUI use it for name space sometimes.
ATTRS : {
aparam : {}
} // Attributes are the parameters sent when the $PAGE->requires->yui_module calls the module.
// Here you can declare default values or run functions on the parameter.
// The param names must be the same as the ones declared
// in the $PAGE->requires->yui_module call.
});
M.local_pluginname = M.local_pluginname || {}; // This line use existing name path if it exists, ortherwise create a new one.
// This is to avoid to overwrite previously loaded module with same name.
M.local_pluginname.init_modulename = function(config) { // 'config' contains the parameter values
alert('I am in the javascript module, Yeah!');
return new MODULENAME(config); // 'config' contains the parameter values
}
}, '@VERSION@', {
requires:['base','another_required_YUI_module', 'a_moodle_YUI_module']
});
</code>
3. Call the javascript in PHP. Again, it is best to do this in a renderer class. (if you copied the previous javascript, 2 javascript alert should appear.)
<code php>
$this->page->requires->yui_module('moodle-local_pluginname-modulename', 'M.local_pluginname.init_modulename',
array(array('aparam'=>'paramvalue')));
</code>
== Full simple example==
Once you understand and run the above quick start, here is simple YUI 3 example. It shows how to use another YUI 3 module in your module, and to use some events.
=== It includes===
* display a parameter value in two javascript alert boxes => demonstrate how to pass a param to the initialize function in two different ways
* display an overlay when you click on an image
* hide the overlay when you click on the body
* some commented code to see how Moodle YUI exception works

=== PHP ===
Create a [https://docs.moodle.org/en/Development:Local_customisation basic local plugin] (in this example it is named hub) in /local/hub/ and add this code into one of the plugin pages:
<code php>
$PAGE->requires->yui_module('moodle-local_hub-comments', 'M.local_hub.init_comments',
array(array('commentids' => '1 , 23 ,45')));
</code>

=== HTML ===
The plugin page should generate this HTML code:
<code xml>

<div id="comments"><img src='http://moodle.org/theme/moodle2/pix/moodle-logo.gif' alt='the image to click on'/></div>


<div id="commentoverlay" class="yui3-overlay-loading">
<div class="yui3-widget-hd">Comment</div>
<div class="yui3-widget-bd">this is a comment</div>
<div class="yui3-widget-bd">this is another comment</div>
</div>
</code>

=== CSS ===
The plugin style.css should contain:
<code css>
/* Hide overlay markup while loading, if js is enabled */
.yui3-js-enabled .yui3-overlay-loading {
top:-1000em;
left:-1000em;
position:absolute;
}

/* Overlay Look/Feel */
.yui3-overlay-content {
padding:3px;
border:1px solid #000;
background-color:#aaa;
}

.yui3-overlay-content .yui3-widget-hd {
padding:5px;
border:2px solid #aa0000;
background-color:#fff;
}

.yui3-overlay-content .yui3-widget-bd {
padding:5px;
border:2px solid #0000aa;
background-color:#fff;
}
</code>

=== JS ===
In /local/hub/yui/comments/comments.js
<code javascript>
YUI.add('moodle-local_hub-comments', function(Y) {

var COMMENTSNAME = 'hub_comments';

//we declare the overlay here so it's accessible to all the extended class function'
var overlay = new Y.Overlay({
srcNode:"#commentoverlay", //the main div with id = commentoverlay
width:"10em",
height:"10em",
xy:[ 0, 0],
visible: false //by default it is not displayed
});

var COMMENTS = function() {
COMMENTS.superclass.constructor.apply(this, arguments);
}

Y.extend(COMMENTS, Y.Base, {

event:null,

initializer : function(params) {

//Example how to retrieve the parameter,
//see what happens if you don't pass the parameter in the call
alert(this.get('commentids')); // You usually use an attribute because
//a attribut can have default value.
//use the ATTRS default value if not passed as parameter
alert(params.commentids); // undefined if not passed as parameter

//render the overlay
overlay.render();

// position the overlay in the middle of the web browser window
var WidgetPositionAlign = Y.WidgetPositionAlign;
overlay.set("align", {
node:"", //empty => viewport
points:[WidgetPositionAlign.CC, WidgetPositionAlign.CC]
});

//attach a show event on the div with id = comments
//we also change the div style to display the click zone
Y.one('#comments').setStyle("border", "1px solid red").on('click', this.show, this);

//uncomment the try content to see how works exception in Moodle
//this exception has been specially created for Moodle
try {
//surely_not_existing_js_function();
} catch (exception) {
new M.core.exception(exception);
}

},

show : function (e) {
overlay.show(); //show the overlay

e.halt(); // we are going to attach a new 'hide overlay' event to the body,
// because javascript always propagate event to parent tag,
// we need to tell Yahoo to stop to call the event on parent tag
// otherwise the hide event will be call right away.

//we add a new event on the body in order to hide the overlay for the next click
this.event = Y.one(document.body).on('click',this.hide,this);
},

hide : function () {
overlay.hide(); //hide the overlay
this.event.detach(); //we need to detach the hide event
//Note: it would work without but create js warning everytime
//we click on the body
}

}, {
NAME : COMMENTSNAME,
ATTRS : {
commentids: {value : 450} //default value (has no purpose in this code except to show you
// how to pass/use a param value)
}
});

M.local_hub = M.local_hub || {};
M.local_hub.init_comments = function(params) {
return new COMMENTS(params);
}

}, '@VERSION@', {
requires:['base','overlay', 'moodle-enrol-notification']
//Note: 'moodle-enrol-notification' contains Moodle YUI exception
});
</code>

==Where are my methods in the IDE?==
Some (all?) IDEs will fail to parse the above structure correctly and will not show you your methods in the structure/navigator pane. If this happens, use JSDoc format to mark the Y.extend() line as being a particular class:
<code javascript>
/**
* @class M.local_hub.init_comments
*/
Y.extend(COMMENTS, Y.Base, {
</code>
This depends to a certain extent on how you choose to instantiate your objects. The above init_widget() method can be replaced with a more class based method like a lot of the YUI library uses.

= What else to read =
Two pages are important to start with when you discover YUI 3
* you should read the [http://developer.yahoo.com/yui/3/base/ base YUI doc]. It is very useful to understand the YUI 3 Moodle module.
* you want to have a look to the [http://developer.yahoo.com/yui/3/examples/ YUI 3 examples]. Always open the examples in a window to have a look to the complete example codes.

[[Category:AJAX]]
[[Category:Javascript]]

== See Also ==
* [[Javascript and YUI 3 FAQ]]
* [[JavaScript FAQ]]

How to create a YUI 3 module

2012-06-10T16:41:07Z

Mattgibson: /* YUI 3 Moodle Module quick start */ Comments typo and spacing

{{Moodle 2.0}}This document explains how to create a YUI 3 module in Moodle.

= The two ways to write a YUI 3 module =
There is two ways to write a YUI 3 module. The two following paragraphs are sourced from a chat with Sam Hemelryk.
==The static module==
The static module is the simpler of the two, in this case you simply put your code into a module.js file within your plugin. Into that file you create a namespace and define any functions or objects you want to use.

Within PHP static modules are also pretty easy to use. The first step if to create a module definition which tells moodle what your module is called, what it requires, and can optionally give it strings.

Once the module is defined you can then use any of the several JS methods for including JS in your page and pass your module definition along.

Whilst this method is simpler to write and understand especially when you are first starting out with JavaScript it isn't as easily flexible and has some quirks that you need will need to overcome, especially with more complex JavaScript.

This method of writing a module should be used if you are just starting out with JavaScript or if the JS solution you are creating is going to be relatively simple in nature.
If you are writing something more complex I would strongly suggest looking at the other method as it will result in cleaner, easier to read code at the end of the day. However it will require you to learn your way around writing a Moodle module.

==The YUI3 Moodle Module==
This method is certainly more complex than the previous method however it is much more flexible and when you have learnt and understand what you are doing it is much quicker to write and more versatile as well. These modules can also easily include other YUI3 Moodle modules, and can choose to include module specific CSS as well.

In this method you create a '''yui''' directory within you plugin directory, and then sub directories for each module you wish to write, you name them the same as you want your module named.
Into the subdirectory you create a JavaScript file with the same name that you gave the subdirectory, e.g.'''/local/myplugin/yui/mymodule/mymodule.js'''
The JS that you then put into this file should then be written in the same way you would write a YUI module, before you ask it certainly requires a good understanding of YUI.

I would recommend this method of writing a module providing you either have an understanding of how to write a YUI module, or you are happy to learn. It normally results in cleaner easier to read code, and if desired can easily be written in such as way as to make it VERY easy to re-use in other bits of code.... particularly helpful if you have several JavaScript objects in play at a time.

= Static module quick start =
1. Create a module.js file somewhere

2. The two ways Moodle can load this file are:

a- the file is in core: declare the file into /lib/outputrequirementslib.php/find_module($component)
<code php>
//example:
case 'core_rating':
$module = array('name' => 'core_rating',
'fullpath' => '/rating/module.js',
'requires' => array('node', 'event', 'overlay', 'io', 'json'));
</code>
b- the file is in a local plugin: the first line of your module should be
<code javascript>
M.local_xxx = {
</code>
xxx being your plugin directory name.

3. Write the module.js
<code javascript>
M.local_hub={
Y : null,
transaction : [],
init : function(Y){
alert('hub module initialisation');
this.Y = Y;
},
}
</code>
4. Call this module. The best place to do this is in your renderer class (since, if a theme overrides the renderer to change the HTML, they may also need to use different JavaScript.
<code php>
$this->page->requires->js_init_call('M.local_hub.init');
You should now have loaded and called your first YUI 3 module in Moodle.
</code>
5. If you want to load your module with some other YUI modules
<code php>
$jsmodule = array(
'name' => 'local_hub',
'fullpath' => '/local/hub/module.js',
'requires' => array("overlay", "anim", "plugin")); //on this line you are loading three other YUI modules
$this->page->requires->js_init_call('M.local_hub.init',
null, false, $jsmodule);
</code>
6. If you want to pass parameter to the init function

PHP:
<code php>
$this->page->requires->js_init_call('M.local_hub.init',
array('this is the param1 value'), false, $jsmodule);
</code>
JS:
<code javascript>
init : function(Y, params){
alert(params);
....
}
</code>
7. Then you should be able to fill the module with your own YUI javascript from [http://developer.yahoo.com/yui/3/examples/ YUI examples].

= YUI 3 Moodle Module quick start =
1. Create the module_name.js file in /local/pluginname/yui/module_name/modulename.js or in /mod/modname/yui/modulename/modulename.js

2. The basic module_name.js structure is:
<code javascript>
YUI.add('moodle-local_pluginname-modulename', function(Y) {
var ModulenameNAME = 'this_is_a_module_name';
var MODULENAME = function() {
MODULENAME.superclass.constructor.apply(this, arguments);
};
Y.extend(MODULENAME, Y.Base, {
initializer : function(config) { // 'config' contains the parameter values
alert('I am in initializer');
}
}, {
NAME : ModulenameNAME, //module name is something mandatory.
// It should be in lower case without space
// as YUI use it for name space sometimes.
ATTRS : {
aparam : {}
} // Attributes are the parameters sent when the $PAGE->requires->yui_module calls the module.
// Here you can declare default values or run functions on the parameter.
// The param names must be the same as the ones declared
// in the $PAGE->requires->yui_module call.
});
M.local_pluginname = M.local_pluginname || {}; // This line use existing name path if it exists, ortherwise create a new one.
// This is to avoid to overwrite previously loaded module with same name.
M.local_pluginname.init_modulename = function(config) { // 'config' contains the parameter values
alert('I am in the javascript module, Yeah!');
return new MODULENAME(config); // 'config' contains the parameter values
}
}, '@VERSION@', {
requires:['base','another_required_YUI_module', 'a_moodle_YUI_module']
});
</code>
3. Call the javascript in PHP. Again, it is best to do this in a renderer class. (if you copied the previous javascript, 2 javascript alert should appear.)
<code php>
$this->page->requires->yui_module('moodle-local_pluginname-modulename', 'M.local_pluginname.init_modulename',
array(array('aparam'=>'paramvalue')));
</code>
== Full simple example==
Once you understand and run the above quick start, here is simple YUI 3 example. It shows how to use another YUI 3 module in your module, and to use some events.
=== It includes===
* display a parameter value in two javascript alert boxes => demonstrate how to pass a param to the initialize function in two different ways
* display an overlay when you click on an image
* hide the overlay when you click on the body
* some commented code to see how Moodle YUI exception works

=== PHP ===
Create a [https://docs.moodle.org/en/Development:Local_customisation basic local plugin] (in this example it is named hub) in /local/hub/ and add this code into one of the plugin pages:
<code php>
$PAGE->requires->yui_module('moodle-local_hub-comments', 'M.local_hub.init_comments',
array(array('commentids' => '1 , 23 ,45')));
</code>

=== HTML ===
The plugin page should generate this HTML code:
<code xml>

<div id="comments"><img src='http://moodle.org/theme/moodle2/pix/moodle-logo.gif' alt='the image to click on'/></div>


<div id="commentoverlay" class="yui3-overlay-loading">
<div class="yui3-widget-hd">Comment</div>
<div class="yui3-widget-bd">this is a comment</div>
<div class="yui3-widget-bd">this is another comment</div>
</div>
</code>

=== CSS ===
The plugin style.css should contain:
<code css>
/* Hide overlay markup while loading, if js is enabled */
.yui3-js-enabled .yui3-overlay-loading {
top:-1000em;
left:-1000em;
position:absolute;
}

/* Overlay Look/Feel */
.yui3-overlay-content {
padding:3px;
border:1px solid #000;
background-color:#aaa;
}

.yui3-overlay-content .yui3-widget-hd {
padding:5px;
border:2px solid #aa0000;
background-color:#fff;
}

.yui3-overlay-content .yui3-widget-bd {
padding:5px;
border:2px solid #0000aa;
background-color:#fff;
}
</code>

=== JS ===
In /local/hub/yui/comments/comments.js
<code javascript>
YUI.add('moodle-local_hub-comments', function(Y) {

var COMMENTSNAME = 'hub_comments';

//we declare the overlay here so it's accessible to all the extended class function'
var overlay = new Y.Overlay({
srcNode:"#commentoverlay", //the main div with id = commentoverlay
width:"10em",
height:"10em",
xy:[ 0, 0],
visible: false //by default it is not displayed
});

var COMMENTS = function() {
COMMENTS.superclass.constructor.apply(this, arguments);
}

Y.extend(COMMENTS, Y.Base, {

event:null,

initializer : function(params) {

//Example how to retrieve the parameter,
//see what happens if you don't pass the parameter in the call
alert(this.get('commentids')); // You usually use an attribute because
//a attribut can have default value.
//use the ATTRS default value if not passed as parameter
alert(params.commentids); // undefined if not passed as parameter

//render the overlay
overlay.render();

// position the overlay in the middle of the web browser window
var WidgetPositionAlign = Y.WidgetPositionAlign;
overlay.set("align", {
node:"", //empty => viewport
points:[WidgetPositionAlign.CC, WidgetPositionAlign.CC]
});

//attach a show event on the div with id = comments
//we also change the div style to display the click zone
Y.one('#comments').setStyle("border", "1px solid red").on('click', this.show, this);

//uncomment the try content to see how works exception in Moodle
//this exception has been specially created for Moodle
try {
//surely_not_existing_js_function();
} catch (exception) {
new M.core.exception(exception);
}

},

show : function (e) {
overlay.show(); //show the overlay

e.halt(); // we are going to attach a new 'hide overlay' event to the body,
// because javascript always propagate event to parent tag,
// we need to tell Yahoo to stop to call the event on parent tag
// otherwise the hide event will be call right away.

//we add a new event on the body in order to hide the overlay for the next click
this.event = Y.one(document.body).on('click',this.hide,this);
},

hide : function () {
overlay.hide(); //hide the overlay
this.event.detach(); //we need to detach the hide event
//Note: it would work without but create js warning everytime
//we click on the body
}

}, {
NAME : COMMENTSNAME,
ATTRS : {
commentids: {value : 450} //default value (has no purpose in this code except to show you
// how to pass/use a param value)
}
});

M.local_hub = M.local_hub || {};
M.local_hub.init_comments = function(params) {
return new COMMENTS(params);
}

}, '@VERSION@', {
requires:['base','overlay', 'moodle-enrol-notification']
//Note: 'moodle-enrol-notification' contains Moodle YUI exception
});
</code>

= What else to read =
Two pages are important to start with when you discover YUI 3
* you should read the [http://developer.yahoo.com/yui/3/base/ base YUI doc]. It is very useful to understand the YUI 3 Moodle module.
* you want to have a look to the [http://developer.yahoo.com/yui/3/examples/ YUI 3 examples]. Always open the examples in a window to have a look to the complete example codes.

[[Category:AJAX]]
[[Category:Javascript]]

== See Also ==
* [[Javascript and YUI 3 FAQ]]
* [[JavaScript FAQ]]

How to create a YUI 3 module

2012-06-10T16:29:41Z

Mattgibson: /* YUI 3 Moodle Module quick start */ Missing semicolon

{{Moodle 2.0}}This document explains how to create a YUI 3 module in Moodle.

= The two ways to write a YUI 3 module =
There is two ways to write a YUI 3 module. The two following paragraphs are sourced from a chat with Sam Hemelryk.
==The static module==
The static module is the simpler of the two, in this case you simply put your code into a module.js file within your plugin. Into that file you create a namespace and define any functions or objects you want to use.

Within PHP static modules are also pretty easy to use. The first step if to create a module definition which tells moodle what your module is called, what it requires, and can optionally give it strings.

Once the module is defined you can then use any of the several JS methods for including JS in your page and pass your module definition along.

Whilst this method is simpler to write and understand especially when you are first starting out with JavaScript it isn't as easily flexible and has some quirks that you need will need to overcome, especially with more complex JavaScript.

This method of writing a module should be used if you are just starting out with JavaScript or if the JS solution you are creating is going to be relatively simple in nature.
If you are writing something more complex I would strongly suggest looking at the other method as it will result in cleaner, easier to read code at the end of the day. However it will require you to learn your way around writing a Moodle module.

==The YUI3 Moodle Module==
This method is certainly more complex than the previous method however it is much more flexible and when you have learnt and understand what you are doing it is much quicker to write and more versatile as well. These modules can also easily include other YUI3 Moodle modules, and can choose to include module specific CSS as well.

In this method you create a '''yui''' directory within you plugin directory, and then sub directories for each module you wish to write, you name them the same as you want your module named.
Into the subdirectory you create a JavaScript file with the same name that you gave the subdirectory, e.g.'''/local/myplugin/yui/mymodule/mymodule.js'''
The JS that you then put into this file should then be written in the same way you would write a YUI module, before you ask it certainly requires a good understanding of YUI.

I would recommend this method of writing a module providing you either have an understanding of how to write a YUI module, or you are happy to learn. It normally results in cleaner easier to read code, and if desired can easily be written in such as way as to make it VERY easy to re-use in other bits of code.... particularly helpful if you have several JavaScript objects in play at a time.

= Static module quick start =
1. Create a module.js file somewhere

2. The two ways Moodle can load this file are:

a- the file is in core: declare the file into /lib/outputrequirementslib.php/find_module($component)
<code php>
//example:
case 'core_rating':
$module = array('name' => 'core_rating',
'fullpath' => '/rating/module.js',
'requires' => array('node', 'event', 'overlay', 'io', 'json'));
</code>
b- the file is in a local plugin: the first line of your module should be
<code javascript>
M.local_xxx = {
</code>
xxx being your plugin directory name.

3. Write the module.js
<code javascript>
M.local_hub={
Y : null,
transaction : [],
init : function(Y){
alert('hub module initialisation');
this.Y = Y;
},
}
</code>
4. Call this module. The best place to do this is in your renderer class (since, if a theme overrides the renderer to change the HTML, they may also need to use different JavaScript.
<code php>
$this->page->requires->js_init_call('M.local_hub.init');
You should now have loaded and called your first YUI 3 module in Moodle.
</code>
5. If you want to load your module with some other YUI modules
<code php>
$jsmodule = array(
'name' => 'local_hub',
'fullpath' => '/local/hub/module.js',
'requires' => array("overlay", "anim", "plugin")); //on this line you are loading three other YUI modules
$this->page->requires->js_init_call('M.local_hub.init',
null, false, $jsmodule);
</code>
6. If you want to pass parameter to the init function

PHP:
<code php>
$this->page->requires->js_init_call('M.local_hub.init',
array('this is the param1 value'), false, $jsmodule);
</code>
JS:
<code javascript>
init : function(Y, params){
alert(params);
....
}
</code>
7. Then you should be able to fill the module with your own YUI javascript from [http://developer.yahoo.com/yui/3/examples/ YUI examples].

= YUI 3 Moodle Module quick start =
1. Create the module_name.js file in /local/pluginname/yui/module_name/modulename.js or in /mod/modname/yui/modulename/modulename.js

2. The basic module_name.js structure is:
<code javascript>
YUI.add('moodle-local_pluginname-modulename', function(Y) {
var ModulenameNAME = 'this_is_a_module_name';
var MODULENAME = function() {
MODULENAME.superclass.constructor.apply(this, arguments);
};
Y.extend(MODULENAME, Y.Base, {
initializer : function(config) { //'config' contains the parameter values
alert('I am in initializer');
}
}, {
NAME : ModulenameNAME, //module name is something mandatory.
//It should be in lower case without space
//as YUI use it for name space sometimes.
ATTRS : {
aparam : {}
} // Attributs are the parameters sent when the $PAGE->requires->yui_module calls the module.
// Here you can declare default values or run functions on the parameter.
// The param names must be the same as the ones declared
// in the $PAGE->requires->yui_module call.
});
M.local_pluginname = M.local_pluginname || {}; //this line use existing name path if it exists, ortherwise create a new one.
//This is to avoid to overwrite previously loaded module with same name.
M.local_pluginname.init_modulename = function(config) { //'config' contains the parameter values
alert('I am in the javascript module, Yeah!');
return new MODULENAME(config); //'config' contains the parameter values
}
}, '@VERSION@', {
requires:['base','another_required_YUI_module', 'a_moodle_YUI_module']
});
</code>
3. Call the javascript in PHP. Again, it is best to do this in a renderer class. (if you copied the previous javascript, 2 javascript alert should appear.)
<code php>
$this->page->requires->yui_module('moodle-local_pluginname-modulename', 'M.local_pluginname.init_modulename',
array(array('aparam'=>'paramvalue')));
</code>
== Full simple example==
Once you understand and run the above quick start, here is simple YUI 3 example. It shows how to use another YUI 3 module in your module, and to use some events.
=== It includes===
* display a parameter value in two javascript alert boxes => demonstrate how to pass a param to the initialize function in two different ways
* display an overlay when you click on an image
* hide the overlay when you click on the body
* some commented code to see how Moodle YUI exception works

=== PHP ===
Create a [https://docs.moodle.org/en/Development:Local_customisation basic local plugin] (in this example it is named hub) in /local/hub/ and add this code into one of the plugin pages:
<code php>
$PAGE->requires->yui_module('moodle-local_hub-comments', 'M.local_hub.init_comments',
array(array('commentids' => '1 , 23 ,45')));
</code>

=== HTML ===
The plugin page should generate this HTML code:
<code xml>

<div id="comments"><img src='http://moodle.org/theme/moodle2/pix/moodle-logo.gif' alt='the image to click on'/></div>


<div id="commentoverlay" class="yui3-overlay-loading">
<div class="yui3-widget-hd">Comment</div>
<div class="yui3-widget-bd">this is a comment</div>
<div class="yui3-widget-bd">this is another comment</div>
</div>
</code>

=== CSS ===
The plugin style.css should contain:
<code css>
/* Hide overlay markup while loading, if js is enabled */
.yui3-js-enabled .yui3-overlay-loading {
top:-1000em;
left:-1000em;
position:absolute;
}

/* Overlay Look/Feel */
.yui3-overlay-content {
padding:3px;
border:1px solid #000;
background-color:#aaa;
}

.yui3-overlay-content .yui3-widget-hd {
padding:5px;
border:2px solid #aa0000;
background-color:#fff;
}

.yui3-overlay-content .yui3-widget-bd {
padding:5px;
border:2px solid #0000aa;
background-color:#fff;
}
</code>

=== JS ===
In /local/hub/yui/comments/comments.js
<code javascript>
YUI.add('moodle-local_hub-comments', function(Y) {

var COMMENTSNAME = 'hub_comments';

//we declare the overlay here so it's accessible to all the extended class function'
var overlay = new Y.Overlay({
srcNode:"#commentoverlay", //the main div with id = commentoverlay
width:"10em",
height:"10em",
xy:[ 0, 0],
visible: false //by default it is not displayed
});

var COMMENTS = function() {
COMMENTS.superclass.constructor.apply(this, arguments);
}

Y.extend(COMMENTS, Y.Base, {

event:null,

initializer : function(params) {

//Example how to retrieve the parameter,
//see what happens if you don't pass the parameter in the call
alert(this.get('commentids')); // You usually use an attribute because
//a attribut can have default value.
//use the ATTRS default value if not passed as parameter
alert(params.commentids); // undefined if not passed as parameter

//render the overlay
overlay.render();

// position the overlay in the middle of the web browser window
var WidgetPositionAlign = Y.WidgetPositionAlign;
overlay.set("align", {
node:"", //empty => viewport
points:[WidgetPositionAlign.CC, WidgetPositionAlign.CC]
});

//attach a show event on the div with id = comments
//we also change the div style to display the click zone
Y.one('#comments').setStyle("border", "1px solid red").on('click', this.show, this);

//uncomment the try content to see how works exception in Moodle
//this exception has been specially created for Moodle
try {
//surely_not_existing_js_function();
} catch (exception) {
new M.core.exception(exception);
}

},

show : function (e) {
overlay.show(); //show the overlay

e.halt(); // we are going to attach a new 'hide overlay' event to the body,
// because javascript always propagate event to parent tag,
// we need to tell Yahoo to stop to call the event on parent tag
// otherwise the hide event will be call right away.

//we add a new event on the body in order to hide the overlay for the next click
this.event = Y.one(document.body).on('click',this.hide,this);
},

hide : function () {
overlay.hide(); //hide the overlay
this.event.detach(); //we need to detach the hide event
//Note: it would work without but create js warning everytime
//we click on the body
}

}, {
NAME : COMMENTSNAME,
ATTRS : {
commentids: {value : 450} //default value (has no purpose in this code except to show you
// how to pass/use a param value)
}
});

M.local_hub = M.local_hub || {};
M.local_hub.init_comments = function(params) {
return new COMMENTS(params);
}

}, '@VERSION@', {
requires:['base','overlay', 'moodle-enrol-notification']
//Note: 'moodle-enrol-notification' contains Moodle YUI exception
});
</code>

= What else to read =
Two pages are important to start with when you discover YUI 3
* you should read the [http://developer.yahoo.com/yui/3/base/ base YUI doc]. It is very useful to understand the YUI 3 Moodle module.
* you want to have a look to the [http://developer.yahoo.com/yui/3/examples/ YUI 3 examples]. Always open the examples in a window to have a look to the complete example codes.

[[Category:AJAX]]
[[Category:Javascript]]

== See Also ==
* [[Javascript and YUI 3 FAQ]]
* [[JavaScript FAQ]]

Plugin contribution

2011-10-10T18:30:52Z

Mattgibson: /* Share code with modules and plugins database */ Added command to zip up a git repo

This page describes the various ways to share and work collaboratively on contributed code. In the past, Moodle CONTRIB code was often stored on the Moodle CVS server. As Moodle code transitions to [https://docs.moodle.org/en/Git Git], CONTRIB code will also be transitioning with a goal of having all code maintained via git repositories by August 2011. Don't worry if you have code on CVS and do not know Git as there are many people willing to help you with the transition especially [https://docs.moodle.org/en/User:Anthony_Borrow Anthony Borrow].

For those neither familiar with CVS nor Git, it is recommended that you [https://docs.moodle.org/en/Git#Books_and_tutorials learn Git basics]. The nice thing about using Git is that it will leave control of the code in the hands of contributor.

*'''Sharing code''' - Contributed code will be shared and maintained using a public Git repository (i.e. github.com, gitorious.org, etc.).
*'''Reviewing code''' - If you would like your code to be tested and reviewed, please create an issue in the [http://tracker.moodle.org/ Moodle Tracker] under [http://tracker.moodle.org/browse/CONTRIB CONTRIB].
*'''Documenting code''' - You can maintain helpful documentation of the features and installation instructions in [https://docs.moodle.org Moodle Docs]
*'''Distributing code''' - You can help others find your code by adding an entry to the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database]
*'''Discussing the code''' - You can discuss the functionality and answer questions about how to use your code in the [http://moodle.org/course/view.php?id=5 Using Moodle forums]. Users can ask questions, discuss possible ideas for improvement, etc. Once the discussion matures to a point where you may want to take action, then you can create an issue in the [http://tracker.moodle.org/ Moodle Tracker].
*'''Maintaining code''' - You can further develop your code by fixing issues, adding features, and responding to other issues with the [http://tracker.moodle.org/ Moodle Tracker]. Each plugin or patch can have its own component in the CONTRIB project; however, you will need to request that the component be created in the CONTRIB project. Once created, users can easily create issues related to your contributed code. The primary maintainer of the code will be assigned as the component lead and have their tracker privileges bumped so that they can manage issues related to their contributed code. Those issues will automatically be assigned to the component lead/primary maintainer.

==The CONTRIB Frequently Asked Question (FAQ)==
'''Question:''' I have written a new block, activity, patch or theme to share with the Moodle community. What is the process for contributing the code?

'''Answer:''' First, thank you for your generosity and desire to share your work with the rest of the Moodle community. Code contributions are highly valued and Moodle wants to encourage creativity and generosity in keeping with [https://docs.moodle.org/en/Pedagogy Moodle's social constructionist pedagogy].

As mentioned, there are various tools to help you share and support your contribution. By using a consistent methodology, your Moodle related code will be more easily found, tested, used, maintained, documented, and evaluated by fellow Moodlers and developers. Learning to use the various tools common among Moodle developers will help you to efficiently and effectively develop, share and maintain your contributed code.

==How to submit code==
You have created some code that you would like to contribute to the Moodle community. The first step is to choose which Git code hosting site you want to use. Both [http://github.com/ github.com] and [http://gitorious.org/ gitorious.org] are popular. Follow the instructions for creating a public repository for your code. This will allow others to download your code as well as suggest possible patches. As you become more familiar with collaborating with others you can also control who else you want to be able to push changes into your repository (i.e. write access).

In order to facilitate a common naming convention of Moodle related repositories, it is suggested that you use the following format: moodle-{plugintype}_{pluginname}. For example, the birthday block has a repository name of moodle-block_birthday and is located at https://github.com/arborrow/moodle-block_birthday. Other developers can fork the code and work from their repositories.

==How to request that your code be tested/reviewed==

#If you do not already have an account on the [http://tracker.moodle.org Moodle Tracker], create one and login.
#Create a new "Task" issue in the "Non-core contributed modules" project. Your issue will be a request that the code be tested and reviewed.
#Provide the link to the repository (i.e. https://github.com/arborrow/moodle-block_birthday)
#Provide a clear description of what the code does and the functionality that it adds to Moodle.
#Provide any other links to supporting documentation

The Contrib Coordinator will then work directly with the code contributor via the Tracker to help evaluate the code, work on resolving any questions/issues found, etc.

*Contributors are encouraged to follow Moodle's coding guidelines [[Coding]].

*Contributors are encouraged to maintain a branch for each major Moodle release (i.e. 1.8, 1.9, etc.). The HEAD branch should be used as the development branch.

*Contributors are encouraged to associate each change made to an issue in the tracker. This practice is done by Moodle core developers and it is a good habit to get into so that you can go back and see why various changes were made to the code. Simple practices like these help to create good documentation of the code as it develops and matures. Commits should begin with the Moodle tracker issue number followed by a brief description of the change.

==How to provide documentation==
Having great code available to the community is wonderful. It is also important to educate users about how to use the code with documentation in [[:en:Main Page|Moodle Docs]]. See [[:en:MoodleDocs:Guidelines for contributors|guidelines for contributors]] for more help.

A documentation page for a contributed module should have some basic elements. A brief introduction of what the code does, a "Features" heading, perhaps a "Installation", "Tips and tricks" and "See also" headings, all with content of course. Sometimes a screenshot is worth 1000 words. In the "See also" put a link to the Modules and Plug database, with a note that this is the place to download versions, and the forum where questions can be answered at moodle.org.

Other information might include: Languages Supported, Known Issues, Supported Versions (for Moodle 1.8, 1.9), and maybe which are being actively supported. The page should be added to the contributed code category by typing <code><nowiki>[[Category:Contributed code]]</nowiki></code> at the bottom of the page.

===Possible format for a contributed code Moodle Docs page===
You can copy and paste the below into your Moodle documentation page. Please add the URL links. '''This is only a suggestion'''.
Start with a 2-4 line introduction. The Plug In Name works with the activity module.
It makes the life of the teacher easier by ...
==Features==
* Add features list or overview description here <nowiki><br></nowiki>
<nowiki> [[Image:Sample_screen_shot|thumb|500px|center|Title of screenshot]]</nowiki>
==Installation==
Place install instructions here
==Tips and tricks==
*Optional section, usually added by users later
==See also==
*[Place http_address_for_M&P_entry_here Name of Entry here] is a Modules and plugins database page that has download links and more information.
*Discussions: [Place http_address_for_moodle_forum_or_thread_here Name of forum]

When no thread or forum exists for discussion, put a link to the Contributed Code forum.
*Discussions: Please create or find a discussion topic in the <nowiki>[http://moodle.org/mod/forum/view.php?id=44 Contributed Code forum]</nowiki>

==Share code with modules and plugins database==
Now you have a place for users to get your code, how will they know it exists? Moodle users can easily find information about contributed code in the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database]. When you add an entry to this database, remember that it is searchable by any field. Every field is not required, but providing as much information as possible will help people who would like to find, read about, and then install your contribution. In particular, the name of the module and the description of its function are important. Screen shots are helpful (but please, not larger than 350px wide!). Links to discussion (on Moodle.org or other forum) and documentation (link to your page in the [https://docs.moodle.org Moodle docs] or another location) should be included if possible.

Users may leave comments on your entry, so please check it periodically for questions and bug reports. If you include contact information or a link to a discussion, your users may be able to contact you more directly. The comments are not emailed automatically.

Keep in mind that entries added to the [http://moodle.org/mod/data/view.php?id=6009 Modules and Plugins database] require approval by a moderator before they will be visible to other Moodle users.

If you are using git to store your code, you will need to export the repository cleanly into a zip file containing one folder, named after your plugin. Use this code to do that:

git archive -o path/to/filename.zip --prefix=yourpluginname/ yourbranchname

==Support code and get feedback with forums==
As users become familiar with the contributed code, discussions about the code are likely to emerge. We strongly urge you to place links to at least one forum at moodle.org in your Modules and Plugins entry as well as in MoodleDocs.

It is important to respond to users who have questions about how to use the code, suggestions for how to make it better, etc. If it looks like there is sufficient need for some contributed code to have its own forum, please create a request via the tracker in the MDL-SITE section. Moodle has included many contributed code projects and ideas into its core.

*[http://moodle.org/mod/forum/view.php?id=44 Contributed code forum] is a generic forum. Maybe create a thread "New Mousetrap module".
*[http://moodle.org/course/view.php?id=5 Using Moodle forums] The English speaking list of forums on many different subjects.
*[http://moodle.org/course/ A list of] other language forums and special areas in Moodle

==Maintain and refine code with Tracker==

In order to facilitate keeping track of feature requests, bugs, and other code issues, the contributor may request that a component be created in the CONTRIB section of the Moodle tracker. (This is the section where you initially made the request to have code included in CVS.moodle.org.)

The contributor can be added to the group of CONTRIB developers in the tracker to manage the issues assigned to them and better coordinate with other developers. Users of the contributed code can then add issues which can be assigned directly to the maintainer. The tracker helps to manage the work flow involved in fixing bugs, working through feature requests, and maintaining the code. When committing changes, maintainers are strongly encouraged to begin the commit comment with a tracker number.

We strongly encourage users to involve themselves in the process of creating a useful issue in tracker. For the developer and code contributor, describing the fix can help clarify the need for the code change. Further, it helps to establish good documentation about how the code developed. Others will be able to identify the issues addressed and understand why a particular decision was made.

==Summary==

It is hoped that following this procedure, will help guide contributors of code in the process of learning the tools and skills used by the Moodle developers. Learning to submit code by using the tracker, work the code with CVS, support the code by providing documentation, share code in Modules and Plugins, maintain the code by using the tracker, and evolve the code by using the Moodle.org forums will assist you in successfully contributing to the Moodle community and working with Moodle's developers.

Throughout this process, the CONTRIB Coordinator is here to encourage and support those contributing code to the Moodle community and fostering the development of tomorrow's Moodle developers.

Eventually, the community may wish for the code to become part of the Moodle core. By following the steps above, the developers will be able to evaluate the merit of the contributed code, understand how users have used the code, see the issues that have emerged and thus have more information to make an informed decision about whether or not to incorporate the contributed code into core.

==Most common recommendations for contributed code==

There are several small issues that the CONTRIB Coordinator will typically check for when reviewing the code prior to committing to the CVS server. These issues help to ensure consistency and quality of code. Any suggestions made by the CONTRIB Coordinator should be considered recommendations aimed to help folks new to the Moodle community collaborate in a way consistent with standard practices within the Moodle community. The suggestions are meant to help avoid potential issues and facilitate the acceptance of your code.

=== Does the file structure conform to Moodle standards? ===
Generally speaking, each file should have an appropriate extension (i.e. php, html, css, txt, etc.). To avoid issues with case sensitivity, folders and files are normally lower case; however, there are exceptions to this. Another common recommendation is to place the lang folder within the block or module rather than asking the user to copy files into the main lang folder. Changes made in the get_string function for Moodle 1.9 and onward make it possible to do this which goes a long way in keeping things modular. Similarly, to respect the modular nature of Moodle if a block requires a library it is usually preferred to keep it as a subdirectory in the block's folder. This can be especially helpful if your code is dependent upon a particular version of an external library.

=== Does the code work without any obvious errors? ===
The CONTRIB Coordinator will try to install the block or module on a fresh Moodle installation and report back any errors. This testing is done with Debugging set to show All PHP notices and errors (not developer mode). The most common notices have to do with attempting to use a variable that has not been initialized or checked for existence.

=== Does the code use the config_plugins table? ===

Contributed blocks and modules are encouraged to make use of the '''config_plugins''' table rather than the config table. Maintainers are encouraged to read the documentation provided for the [http://xref.moodle.org/lib/moodlelib.php.html#get_config get_config()] and [http://xref.moodle.org/lib/moodlelib.php.html#set_config set_config()]] functions in the /lib/moodlelib.php file to help ensure that the footprint for the global $CFG variable does not become bloated.

=== Does the code follow the [[Coding|Coding Guidelines]]? ===
The CONTRIB Coordinator will look at the code for general readability and point out any obvious deviations from the [[Coding|Coding Guidelines]]. While not all code needs to conform with each and every guideline, maintainers are encouraged to follow those guidelines as closely as possible. One useful tool for Moodle 2.0 is the [http://moodle.org/mod/data/view.php?d=13&rid=4682|Code checker local plugin] which helps to identify many issues.

==See also==

*[[Migrating contrib code to 2.0]]
*[[contrib]] CONTRIB is an area in the Moodle CVS
*[[:en:Translation]] for information on the translation of contributed code
*[[Overview]]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=99037 Best practices for code modification?] forum discussion

[[Category:Guidelines for contributors]]

File API

2011-05-19T13:30:24Z

Mattgibson: /* List area files */ Added code to list files as links

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

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

==File areas==

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

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

===Naming file areas===

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

==Serving files to users==

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

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

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

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

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

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

==Getting files from the user==

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

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

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

</code>

===Moving files around===

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

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

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

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

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

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

Or as links...

<code php>
$out = array();

$fs = get_file_storage();
$files = $fs->get_area_files($contextid, 'mod_assignment', 'submission', $submission->id);

foreach ($files as $file) {
$url = "{$CFG->wwwroot}/pluginfile.php/{$file->get_contextid()}/mod_assignment/submission}";
$filename = $file->get_filename();
$fileurl = $url.$file->get_filepath().$file->get_itemid().'/'.$filename;
$out[] = html_writer::link($fileurl, $filename);
}

$br = html_writer::empty_tag('br');

return implode($br, $out);
</code>

=== Create file ===

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

<code php>
$fs = get_file_storage();

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

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

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

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

=== Read file ===

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

<code php>
$fs = get_file_storage();

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

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

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

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

=== Delete file ===

<code php>
$fs = get_file_storage();

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

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

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

==See also==

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

[[Category:Files]]

XMLDB defining an XML structure

2011-05-06T15:51:47Z

Mattgibson: /* Conventions */ Fixed link

[[XMLDB Documentation|XMLDB Documentation]] > [[XMLDB roadmap|Roadmap]] > Defining one XML structure
----

== Justification ==

Before Moodle 1.7, all the DB install and upgrade was developed twice (once to handle MySQL installations and another to handle PostgreSQL installations). This approach, although working, has caused some headaches in the past, mainly because it was really difficult to keep both lines of development 100% on sync. Some developers do they work against one RDBMS and it was complex to develop to the other one (two test environments, skills on both databases, slower development cycle...). And all this was happening with ''only'' two supported RDBMS!

One of the main objectives of Moodle 1.7 is to extend the the number of supported RDBMS to other flavours (more exactly, to Oracle and MSSQL). And the old approach (one line of development for each DB) could become an absolute nightmare.

Because of this we have planned to build one structure to define all the DB objects used by Moodle. This structure will provide the necessary level of abstraction to be shared by all the RDBMS systems, so the "multiple lines of development" explained in the previous paragraph will be out forever, giving us one robust and well defined way to handle DB objects independently of the underlying RDBMS being used.

== Implementation ==

Initially all our best wishes were to use the [http://phplens.com/lens/adodb/docs-datadict.htm#xmlschema AdoDB XML Schema]. As Moodle is using ADOdb libraries to communicate with databases it sounded like the natural approach to solve the problem. But, finally, two reasons prevented us to use it:

# Although working, it seems to be one feature in progress, with important changes/evolutions arriving at the time of write this document.
# Its lack of support for "prefixes" (one Moodle key feature, to allow multiple instances to run in the same server), would force us to create some awful tricks to generate the objects.

So, finally, we decided to build our own XML files, with everything we need to define every object present in the DB.

== The XMLDB editor ==
[[XMLDB_editor | Main article]]

Although the XML is pretty simple to read (and to write), one of the major drawbacks was its easy and error-prone adoption by the developers. Also some problems with versioning systems getting crazy with XML files (thanks ML!) pointed us to the requirement to use one high-density format (it means, physically '''long lines''') in our XML files.

After some intense thoughts we decided to build one specialised editor for our XML format. This editor should be easy to use and provide support for all the objects present one Moodle DB. And it's done (and will support future enhancements easily, we hope).

The XMLDB Editor makes the addition of tables/fields/keys/indexes practically a trivial task, allowing the developer to spend the time coding and improving things instead of fighting against XML files and the errors caused by manual editing (of course, the developer is free to use such extra-time as desired, beers, dance, books, music...) ;-)

All the new '''install.xml''' files, present under each '''db''' directory in Moodle can be edited (and we recommend it) with just some clicks and keystrokes. Those '''install.xml''' will contain all the info needed to generate the specific objects needed for each RDBMS supported. Obviously, such files, are the neutral replacement for all the *.sql files used until now.

=== Launching ===

Just login to your server as an administrator and, under the Miscellaneous tab of the Administration Block, you'll see a new link pointing to the "XMLDB Editor".

One '''important note''' is that, to be able to handle files properly, the web server needs write access to all those "db" directories where the "install.xml" files reside (and to the files themselves, of course). ;-)

That's all!

=== Use===

We really think the XMLDB Editor is pretty easy to use, so here you won't see a complete guide to use it. We highly recommend you to play with it for a while, viewing how it works and how it modifies the '''install.xml''' files.

It's organised in a top-botton structure, where you start '''loading''' (or '''creating''') a new XMLDB file. Then, you can '''edit''' such file and its '''general structure''' will be showed. This structure have two type of elements, '''tables''' and '''statements''' and the XMLDB Editor allows you to '''add''', '''edit''', '''delete''', and '''move''' them easily. Also, for initial creation of tables, one small but effective '''reverse-enginery''' tool has been developed (only under MySQL) allowing you to retrofit any table from the DB to the XMLDB Editor.

'''Note: If you can't click on the create links....''' you must first create the /db folder (as shown in the list, but it may not really exist) and then make sure it is writeable by the webserver

While editing tables you will see their '''fields''', '''keys''' and '''indexes''' and you'll be able to handle all them easily. Note that some fields can be no-editable. It uses to be because they are being used in some way (part of one key or index) and the idea is to warn you about that.

Fields can be edited and you can specify their '''name''', '''type''', '''length''', '''decimals''', '''null-ability''', '''defaults''' and so one. Exactly the same for both '''keys''' and '''indexes'''.

While editing statements, you must think about them like "collections of sentences". Once you select the '''type''' (only inserts are allowed for now) and '''table''' you are interested you'll be able to introduce the exact values easily, being able to '''duplicate''' them easily to gain some speed if you have a lot of sentences in your development. Sentences can be '''edited''' and '''deleted''' easily too.

One interesting feature is that all the XMLDB Editor pages allow you to enter one '''comment''' about the item being modified (table, index, key, field, statement...). Use it at your entire needs, sure it helps other developers to understand a bit more the DB model.

Please, don't forget to read and understand the next section, where we talk about '''some important guidelines''' to create and handle XMLDB files.

== Conventions ==

Apart of the [[Database| Database Structures guidelines]], some more conventions should be followed:

# About names:
## All lowercase names (tables, indexes, keys and fields).
## Table names and field names must use only a-z, 0-9 and _ chars. Table names can be at most 28 characters long; column names at most 30 characters.
## Key and index names under the XMLDB Files must be formed by concatenating the name of the fields present in the key/index with the '"-" (minus) character.
## Primary key always must be named "primary" (this is one exception to the previous convention).
## It's highly recommended to avoid [[XMLDB_reserved_words|reserved words]] completely. We know we have some of them now but they should be completely out for next releases.
# About NULLS
## Avoid to create all the fields as NOT NULL with the ''silly'' default value <nowiki>''</nowiki> (empty string). The underlying code used to create tables will handle it properly but the XMLDB structure must be REAL. Read more in the [[XMLDB_Problems#NOT_NULL_fields_using_a_DEFAULT_.27.27_clause|Problems Page]].
# About FOREIGN KEYS
## Under the tables of every XMLDB file, you must define the existing '''Foreign Keys''' (FK) properly. This will allow everybody to know a bit better the structure, allow to evolve to a better constrained system in the future and will provide the underlying code with the needed info to create the proper indexes.
## Note that, if you define any field combination as FK you won't have to create any index on that fields, the code will do it automatically!
## This convention is only applicable for relations INSIDE one file. Don't generate FK constraints against other files (courseid, userid), use indexes there.
## Respect Convention 1.3
# About UNIQUE KEYS
## Declare any fields as UNIQUE KEY (UK) only if they are going to be used as target for one FK. Create unique indexes instead.
## Respect Convention 1.3

== One example: the assignment module ==

Here we are going to examine the [http://cvs.moodle.org/moodle/mod/assignment/db/install.xml?view=markup current implementation of the XMLDB Schema for the assignment module] (a simple one). It has been completely generated with the XMLDB Editor but it's nice to know a bit more about the XML internals.

As you can see the structure is pretty simple:

* XMLDB
** TABLES, one or more, each one with
*** FIELDS
*** KEYS
*** INDEXES
** STATEMENTS, none or more, each one with
*** SENTENCES

First of all you should note that all the elements contain the '''PREVIOUS''' and '''NEXT''' attributes. They allow us to keep everything ordered although it isn't meaningful at all from the RDBMS perspective. Also the '''COMMENT''' field is present everywhere to be used as desired.

=== The TABLE element ===

We can ignore the TABLE element, as it's simply one container for the internals (FIELDS, KEYS and INDEXES). Let's go to examine them a bit more:

==== The FIELD element ====

It maps with one field in the DB (obviously). For each field you can define its '''name''', '''type''' (from a list of [[XMLDB column types|neutral types]]), '''length''', '''decimals''' (for some types), '''notnull''' (true/false), '''unsigned''' (true/false), '''sequence''' (if it's autonumeric or serial, true/false), '''enum''' (true/false), '''enumvalues''' (the list of values if the field has been declared as enum, for example <tt>'frog','toad','newt'</tt>) and '''default''' (to assign a default value).

So, in our example, we have two tables, assignment and assignment_submissions, each one with its own fields, defining all the information related above. Please note that naming conventions are followed.

==== The KEY element ====

Here is where all the PRIMARY KEYS (PK), UNIQUE KEYS (UK) and FOREIGN KEYS (FK) will be defined. For each key we define its '''name''', '''type''', '''fields''' (that belongs to it) and optionally (if the key is one FK) the target '''reftable''' and '''reffields'''.

In our example, the assignment table has one (mandatory!) PK (called, "primary", rules are rules) built with the "id" field.

The other table, the "assignment_submissions" one, also has its PK (called "primary" once more) and one FK, with the field "assignment" pointing to the field "id" of the table "assignment". Note that the FK follows the name conventions and its name is, simply, the name of the fields being part of it ("assignment"). Also, the FK has as target to one PK of the same module.

Finally, note that there isn't any index created for all these keys. Moodle will generate them automatically when the table is created. All the keys will have their corresponding index. Point. ;-)

==== The INDEX element ====

Where all the indexes will be defined. For each index you can define its '''name''', '''unique''' (true/false) and the '''fields''' that conform it. Please note that naming conventions are followed.

Also, some "obvious index", like the one based in the "assignment" field of the "assignment_submissions" table doesn't exist. Yes, you know why: Because such column has been defined as a FK and the index will be automatically created (see previous section).

=== The STATEMENT element ===

This is the other '''big container''' in the XMLDB Schema (at the same level as the '''TABLES''' one) and we can define its '''name''', '''type''' (only insert allowed for now) and '''table''' (against the sentences will be executed).

Every statement is a collection of '''sentences'''

==== The SENTENCE element ====

Each sentence implies one simple action to be performed against the DB and it can be defined as the "missing part of the SQL statement". In our example, we have one statement, of type "insert" on table "log_display". With this Moodle knows the initial part of the sentence, i.e:

INSERT INTO log_display

and then the text will be added to create this:

INSERT INTO log_display
(module, action, mtable, field)
VALUES
('assignment', 'view', 'assignment', 'name')

There is one important trick when handling sentences, although they aren't in the assignment example. Take a look to the [http://cvs.moodle.org/moodle/lib/db/install.xml?view=co Core Tables XML Schema] (it's a huge one!). If you go near the end, to the statements section, you will see some sentences like this:

<SENTENCE TEXT="....VALUES ('user', 'view', 'user', 'CONCAT(firstname," ",lastname)')"/>

Such "CONCAT" function isn't standard at all (only MySQL supports it), but don't worry, we'll transform it to the correct concatenation operators for other RDBMS. Just be sure to use the syntax showed above.

== DTD and XML schema ==

Not sure if this will be usable for somebody but here you can find one [http://cvs.moodle.org/moodle/lib/xmldb/xmldb.dtd?view=co automatically generated DTD] for the XMLDB files. Also one [http://cvs.moodle.org/moodle/lib/xmldb/xmldb.xsd?view=co automatically generated XML Schema] is available. Any improvement/fix to them will be welcome!

== See also ==

* [[XMLB List of files to create|List of files to create]]: The list of files to be created from scratch. Used to follow the progress.
* http://www.hitsw.com/xml_utilites/: One online XML-DTD-Schema converter.

[[Category:XMLDB]]
[[Category:DB]]

Creating a theme settings page

2011-05-03T22:56:58Z

Mattgibson: /* How settings pages work in Moodle */ typo

{{Template:Themes}}{{Moodle 2.0}}This document looks at how to create a settings page for your theme and how to make use of those settings within the CSS and layout files for your theme.

This is a pretty advanced topic and will require that you have at least an intermediate knowledge of PHP, CSS, and development in general.

==Before we begin==
[[Image:Theme.settings.page.03.png|350px|thumb|Our end goal. The settings page.]]
[[Image:Theme.settings.page.10.png|350px|thumb|And what it can do.]]
There is a huge body of knowledge that we must cover in following through this document and as such I think the best way to write this is as a tutorial.

My intentions for this tutorial are to replicate the standard theme but with a settings page that allows the administrator to set a background colour, set a logo to use with the page, and probably several other minor settings to change the way in which the theme is displayed.

I will start this tutorial by creating a new theme which will be largely a copy/paste of the current standard theme. I expect that anyone working through this tutorial has previously read the tutorial I wrote on [[Themes 2.0 creating your first theme|creating your first theme]]. If you haven't go read it now because I'm not going to go into much detail until we get to the actual process of customising the theme and introducing the settings page.

So before we finally get this started please ensure you can check off everything on the following requirements list.
* Have a Moodle installation that has already been installed and configured and is ready to use.
* Have full read/write access to that installation.
* Be prepared to delete that installation at the end of this... we will destroy it!
* Have a development environment prepared and ready to use. This includes:
** Your favourite editor installed, running, and pointed at the themes directory of your installation.
** Your browser open and your site visible.
** A bottomless coffee pot... decaf won't help you with this one.
* Have set the following settings:
** '''themedesignermode''' if you don't know what this is please read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.
** '''allowthemechangeonurl''' turn this on, it allows you to change themes on the URL and is very handy when developing themes. ''Site Administration > Appearance > Themes > Theme settings''
** '''langstringcache''' if you don't turn this off you won't see your strings when they are added. ''Site Administration > Language > Language settings''
* And finally an insane ambition to create a customisable theme.

For those interested the theme that I create throughout this tutorial can be downloaded from the forum post in which I announce this document: http://moodle.org/mod/forum/discuss.php?d=152053
<br style="clear:right;" />

==Our goals for this tutorial==
The following is just a list goals that I hope to achieve during this tutorial. They are laid out here so that I can easily refer back to them and so that you can easily find them.
# Create a new theme called '''demystified''' based upon the standard theme within Moodle 2.0.
# Make some minor changes to that theme to allow us to more easily see what is going on.
# Create a settings page for the demystified theme.
# Add several settings to our settings page.
# Use some of those settings to alter our CSS.
# Use the rest of those settings within our layout file..
# Discuss the good, the bad, and limits of what we have just created.

So I can see you are all very excited about this point and that you would love to know what settings we are going to create; So here they are:

A setting to ...
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

==Creating the demystified theme==
Before we start here I want to remind you that I am going to look at this only briefly as I am making the assumption that you have read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.

Well lets get into it....

The first thing we need to do is create a directory for our theme which we will call demystified.

So within your Moodle directory create the following folder '''moodle/theme/demystified'''. At the same time you can also create the following files and folders which we will get to soon.
* The file '''moodle/theme/demystified/config.php''' for our config information.
* The directory '''moodle/theme/demystified/layout''' for our layout files.
* The directory '''moodle/theme/demystified/style''' for our css files.
* The file '''moodle/theme/demystified/style/core.css''' which will contain our special CSS.

Next we will copy the layout files from the base theme to our new theme demystified. We are basing the demystified theme on the standard theme however that doesn't use it's own layout files it uses the base theme's layout files so those are the ones we want.

The reason that we are coping these layout files is that later on in this tutorial we will be modifying them to make use of our new settings... so copy all of the layout files from '''moodle/theme/base/layout''' to '''moodle/theme/demystified/layout'''.

There should be three files that you just copied:
# embedded.php
# frontpage.php
# general.php

Now we need to populate demystified/config.php with the settings for our new theme. They are as follows:
<code php>
$THEME->name = 'demystified';
</code>
Simply sets the name of our theme.

<code php>
$THEME->parents = array('standard','base');
</code>
This theme is extending both the standard theme and the base theme. Remember when extending a theme you also need to extend its parents or things might not work correctly.

<code php>
$THEME->sheets = array('core');
</code>
This tells our theme that we want to use the file '''demystified/style/core.css''' with this theme.

<div style="height:300px;overflow-y:scroll;">
<code php>
$THEME->layouts = array(
// Most backwards compatible layout without the blocks - this is the layout used by default
'base' => array(
'file' => 'general.php',
'regions' => array(),
),
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// part of course, typical for modules - default page layout if $cm specified in require_login()
'incourse' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Server administration scripts.
'admin' => array(
'file' => 'general.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// My dashboard page
'mydashboard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),

// Pages that appear in pop-up windows - no navigation, no blocks, no header.
'popup' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
// Embeded pages, like iframe/object embeded in moodleform - it needs as much space as possible
'embedded' => array(
'file' => 'embedded.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
// This must not have any blocks, and it is good idea if it does not have links to
// other places - for example there should not be a home link in the footer...
'maintenance' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
);
</code>
</div>
Now that all looks very complicated however its really not too bad as it is just copied from the base theme's config.php file. We can do this because we copied the layout files from the base theme to begin with and for the time being there are no changes that we wish to make. Simply open up '''theme/base/config.php''' and copy the layouts from there.

And that is it. The config.php file for our demystified theme is complete. The full source is shown below:
<div style="height:300px;overflow-y:scroll;">
<code php>
<?php

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* The demystified theme config file
*
* This theme was created to document the process of adding a settings page to a theme
*
* @copyright 2010 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// The name of our theme
$THEME->name = 'demystified';

// The other themes this theme extends
$THEME->parents = array('standard','base');

// The CSS files this theme uses (located in the style directory)
$THEME->sheets = array('core');

// The layout definitions for this theme
$THEME->layouts = array(
// Most backwards compatible layout without the blocks - this is the layout used by default
'base' => array(
'file' => 'general.php',
'regions' => array(),
),
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// part of course, typical for modules - default page layout if $cm specified in require_login()
'incourse' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Server administration scripts.
'admin' => array(
'file' => 'general.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// My dashboard page
'mydashboard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),

// Pages that appear in pop-up windows - no navigation, no blocks, no header.
'popup' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
// Embeded pages, like iframe/object embeded in moodleform - it needs as much space as possible
'embedded' => array(
'file' => 'embedded.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
// This must not have any blocks, and it is good idea if it does not have links to
// other places - for example there should not be a home link in the footer...
'maintenance' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
);
</code>
</div>

The screenshot below shows both the directory structure we have now created and the theme presently.

[[Image:Theme.settings.page.01.png]]

To view the theme so far open you browser and enter the URL of your site followed by '''?theme=demystified'''. You should see the theme that we just created which will look exactly like the base standard theme.

The final thing that we want to do is add a little bit of CSS to the demystified theme that will both visually set this theme apart from the standard theme and second build a the base which our settings can later extend.

I added the following snippet of CSS to the file '''demystified/style/core.css'''.
<code css>
html {background-color:#DDD;}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
</code>

The CSS that we have just added to our theme sets a couple of colours on the front page. Presently this is the only CSS I will add, I know it isn't complete by any means but it achieves it's purpose as the screenshot below illustrates.

[[Image:Theme.settings.page.02.png|715px|thumb|left|The newly styles demystified theme]]<br style="clear:both;" />

And with that I will move on to the real purpose of this tutorial, creating the settings page

==Setting up the settings page==
With the demystified theme set up it is time to create the settings page. This is where the real PHP fun begins.

For those of you who happen to be familiar with development of modules, blocks or other plugin types you have probably encountered settings pages before and this is not going to be any different.

However for those who haven't which I imagine is most of you this is going to be quite a challenge. I will try to walk through this step by step however if at any point you get stuck don't hesitate to ask in the forums as I imagine you will get a speedy response.

===How settings pages work in Moodle===
Settings pages can be used by nearly every plugin type, of which themes is of course one. The way in which it all works isn't too tricky to understand.

All of the settings for Moodle can be configured through the administrator interfaces when logged in. I am sure that everyone here has seen those pages and has changed a setting or two before so you will all know what I am talking about. Well the settings page for a theme is no different. It will be shown in the administration pages tree under '''Appearance > Themes''' and all we have to do is tell Moodle what settings there are.

This is done by creating a settings.php file within our theme into which we will add code that tells Moodle about the settings we want to add/use.

When telling Moodle about each setting we are simply creating a new ''admin_setting'' instance of the type we want and the properties we want and then adding it to our settings page.

There is really not much more too it at this level. Things can get very complex very fast so the best thing we can do now is start creating our settings.php file for the demystified theme and see where it leads us.

===Creating the settings page===
So as mentioned before we need a settings.php file which we will create now. To begin with create the file '''theme/demystified/settings.php''' and open it in your favourite editor so its ready to go.

Before we start adding code however lets just remember the settings that we want to create:
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

Alright.

Now thinking about this the first setting is as basic as it gets, all we need is a text box that the user can type a colour into.

The second is to allow a logo to be used in the header of each page. What we want here is a path but should it be a physical path e.g. C:/path/to/image.png or should it be a web path e.g. <nowiki>http://mysite.com/path/to/image.png</nowiki>?
For the purpose of this tutorial I am going to go with a web path because it is going to be easier to code and will hopefully be a little easier to understand to begin with.

The third setting is a little more complex. For this I want a drop down box with some specific widths that the administrator can select.

The forth and the fifth settings are both pretty straight forward, there we want a textarea into which the user can enter what ever they want and we will do something useful with it.

Now that we have an understanding about the settings we wish to define pull up your editor and lets start coding....

<code php>
<?php

/**
* Settings for the demystified theme
*/

$temp = new admin_settingpage('theme_demystified', get_string('configtitle','theme_demystified'));
</code>
This is the first bit of code we must enter, the first line is of course just the opening php tag, secondly we have a comment that describes this file, and then we get create a new '''admin_settingspage object'''.

This admin_settingspage object that we have just created is a representation of our settings page and is the what we add our new settings to. When creating it we give it two arguments, first the name of the page which is in this case '''theme_''themename''''' and the title for the page which we get with the get_string method.

At the moment I'm not going to worry about adding the string, we will get to that later once we have defined all of our settings.

====Background colour====

With the page now created as ''$temp'' lets add our first setting: Background colour.

<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$temp->add($setting);
</code>
Thankfully this isn't as difficult as it initially looks.

The first line of code is creating a variable for the name of the background colour setting. In this case it is '''theme_demystified/backgroundcolor'''.

The name is very important, for the setting to be usable we have to follow a strict naming convention. '''theme_''themename''/''settingname''''' where '''''themename''''' is the name of the theme the setting belongs to and '''''settingname''''' is the name for the setting by which we will use it.

The second line of code creates a variable that contains the title of the setting. This is what the user sees to the right of the setting on the settings page and should be a short description of the setting. Here we are again using the ''get_string'' method so we will need to remember to add that string later on.

The third line of code sets the description. This should describe what the setting does or how it works and again we will use the get_string method.

The fourth line creates a variable that will be used as the default value for the setting. Because this setting is a colour we want an HTML colour to be the default value.

The fifth line is where we put it all together. Here we create a new '''admin_setting_configtext''' object. This object will represent the background colour setting.

When we create it we need to give it 6 different things.
# The name of the setting. In this case we have a variable '''$name'''.
# The title for this setting. We used the variable '''$title'''.
# The description of the setting '''$description'''.
# The default value for the setting. '''$default''' is the variable this.
# The type of value we want the user to enter. For this we have used PARAM_CLEAN which tells Moodle to get rid of any nasties from what the user enters.
# The size of the field. In our case 12 characters will be plenty.

The sixth and final line of code adds our newly created setting to the administration page we created earlier.

That is it we have successfully created and added our first setting, however there are several more to settings to do, and there are a couple of important things that you need to be aware of before we move on.

First: There are several different types of settings that you can create and add to a page, and each one may differ in what they need you to give them. In this case it was name, title, description, default, type, and size. However other settings will likely require different things. Smart editors like Netbeans or Eclipse can tell you what is required, otherwise you will need to research it.

Second: Normally settings are declared on one line as follows:
<code php>
$temp->add(new admin_setting_configtext('theme_demystified/backgroundcolor', get_string('backgroundcolor','theme_demystified'), get_string('backgroundcolordesc', 'theme_demystified'), '#DDD', PARAM_CLEAN, 12));
</code>
While this is structurally identical as all we have done is move everything onto one line and do away with the variables it is a little harder to read when you are learning all of this.

====The logo file====
Time to create the second setting that will allow the user to enter a URL to an image they wish to use as the logo on their site.
<code php>
// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$temp->add($setting);
</code>
The first thing that you will notice about this setting that it is very similar to the first setting, in fact all we have changed is the name, title, description, and default value. We have however changed the value type from PARAM_CLEAN to PARAM_URL, this makes sure the user enters a URL. You will also notice that for this one we don't set a size for the field as we have no idea how long the URL will be.

====Block region width====
The third setting should allow the user to set a width for the block regions that will be used as columns.

For this setting I want to do something a little different from the previous two, here I want to use a select box so that the user selects a width for the column from a list I provide.
<code php>
// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$temp->add($setting);
</code>
So looking at the code: The first four lines you will recognise. $name, $title, $description, and $default are all being set.

The fifth line of code however introduces something new. Of course in order to have a select box we have to have options, in this case we have an array of options stored in the variable $choices.

The array of options is constructed of a collection of '''''value''' => '''label''''' pairs. Notice how we don't add '''px''' to the value. This is is very intentional as later on I need to do a little bit of math with that value so we need it to be a number.

The lines after should look familiar again, the only difference being that instead of a ''admin_setting_configtext'' setting we have created a ''admin_setting_configselect'' for which we must give the choices for the select box as the fifth argument.

Woohoo, we've just created our first select box setting.

====Foot note====
Now to create the foot note setting. Here we want the user to be able to enter some arbitrary text that will be used in the footer of the page. For this I want the user to be able to enter some HTML so I will create an editor setting.
<code php>
// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$temp->add($setting);
</code>
How simple is that!

It is just about identical to the first two settings except that for this we have created a ''admin_setting_confightmleditor'' setting rather than a text setting.

Note: You can also set the columns and rows for the editor setting using the fifth and sixth arguments.

====Custom CSS====
The final setting is to allow the user to add some custom CSS to the theme that will be used on every page. I want this to be a plain textarea into which the user can enter CSS.
<code php>
// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);
</code>
Just like the editor or text settings. It's getting very easy now!

====Finishing settings.php====
With all of our settings defined and added to our page that we created right at the beginning it is time to finish it all off.
<code php>
// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
The above line of code is the final line for the page. It is adding the page that we have created '''$temp''' to the admin tree structure. In this case it is adding it to the themes branch.

The following is the completed source for our settings.php ..... for your copy/paste pleasure.
<div style='height:300px;overflow:auto;'>
<code php>
<?php

/**
* Settings for the demystified theme
*/

// Create our admin page
$temp = new admin_settingpage('theme_demystified', get_string('configtitle','theme_demystified'));

// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$temp->add($setting);

// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$temp->add($setting);

// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150, 170, 200, 240, 290, 350, 420);
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$temp->add($setting);

// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$temp->add($setting);

// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);

// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
</div>

===Creating a language file and adding our strings===
As I'm sure none of you have forgotten, throughout the creation of the our settings.php page, we used a lot of strings that I mentioned we would set later on. Well now is the time to set those strings.

First up create the following directories and file for our language strings:
* Directory '''theme/demystified/lang'''
* Directory '''theme/demystified/lang/en'''
* File '''theme/demystified/lang/theme_demystified.php'''

What we have created here is the required structure for Moodle to start looking for language strings.

First Moodle locates the lang directory, once found it looks within that directory for another directory that uses the character code for the language the user has selected, by default this is '''en''' for English. Once that is found it looks for the appropriate language file, in this case '''theme_demystified.php''' from which it will load all language strings for our theme.

If English isn't your chosen language simply replace the ''en'' directory with one that uses your chosen languages character code (two letters).

We can now add our language strings to '''theme/demystified/lang/theme_demystified.php'''. Copy and paste the following lines of PHP into this file.
<code php>
<?php

/**
* This file contains the strings used by the demystified theme
*/

$string['backgroundcolor'] = 'Background colour';
$string['backgroundcolordesc'] = 'This sets the background colour for the theme.';
$string['configtitle'] = 'Demystified theme';
$string['customcss'] = 'Custom CSS';
$string['customcssdesc'] = 'Any CSS you enter here will be added to every page allowing your to easily customise this theme.';
$string['footnote'] = 'Footnote';
$string['footnotedesc'] = 'The content from this textarea will be displayed in the footer of every page.';
$string['logo'] = 'Logo';
$string['logodesc'] = 'Enter the URL to an image to use as the logo for this site. Should be http://www.yoursite.com/path/to/logo.png';
$string['regionwidth'] = 'Column width';
$string['regionwidthdesc'] = 'This sets the width of the two block regions that form the left and right columns.';
</code>

In the above lines of code I have added an entry for each language string we used within ''settings.php''. When adding language strings like this make sure you use single quotes and try to keep things alphabetical - it helps greatly when managing strings.

Now when we view the settings page there will not be any errors or strings missing.

===Having a look at what we have created===
Now that we have created our settings page (settings.php) and added all of the language strings it is time to have a look at things in your browser.

Open your browser and enter the URL to your site. When you arrive at your site login as an administrator.

If you are not redirected to view the new settings change your URL to <nowiki>http://www.yoursite.com/admin/</nowiki> and your will see a screen to set the new theme settings we have just created. This lets us know that everything has worked correctly.

At any point now you are able to log in as administrator and within the settings block browse to '''Site administration > Appearance > Themes > Demystified theme''' to change those settings.

The screenshot below shows you what you should see at this point:

[[Image:Theme.settings.page.03.png|715px|thumb|left|The settings page we just created]]
<br style="clear:both;" />

==Using the settings in CSS==
With the settings page now created and operational it is time to make use of our new settings. The settings that we want to use within our CSS is as follows:

; backgroundcolor : Will be used to set the background colour in CSS.
; regionwidth : Will be the width of the column for CSS.
; customcss : Will be some custom CSS to add to our stylesheet.

At this point those names are the names we used for our setting with the slash and everything before it having been removed.

Before we start tearing into some code it is important that we have a look at what we are going to do and how we are going to go about it.

===How it all works within Moodle===
The first thing to understand is that while Moodle allows you to create a settings page and automates it inclusion and management right into the administration interfaces there is no smart equivalent for using the settings. This is simply because there is no way to predict how people will want to use the settings.

However don't think of this as a disadvantage, in fact it is quite the contrary. Although we can't just ''use'' our settings we can take full control over how and where we use them. It means it will take a little more code but in the end that will work to our advantage as we can do anything we want.

Moodle does help us out a little but not in an obvious way. The first thing that Moodle does is look for a config variable '''csspostprocess''' that should be the name of a function which we want called to make any changes to the CSS after it has been prepared.

The second thing Moodle does is include a lib.php from the theme's directory if one exists (also for the themes the current theme extends.) which ensures that as long as we write our code within '''theme/demystified/lib.php''' it will be included and ready to be used.

The third and final thing Moodle does that will help us out here is ensure that by the time any of code is ready to execute the settings have been prepared and are ready to be used within a theme config object which is passed into our ''csspostprocess'' function.

===Our plan===
As you have already probably guessed we will need to create a function to make the changes to the CSS that we want. We will then set the theme config option '''$THEME->csspostprocess''' to the name of our function.

By doing this when Moodle builds the CSS file it will call our function afterwards with the CSS and the theme object that contains our setting.

Now we know that we will use the ''csspostprocess'' function but how are we going to change the CSS, we could get the function to add CSS, or we could get the function to replace something within the CSS. My personal preference is to replace something within the CSS, just like what is happening with images. If you want to use an image within CSS you would write <nowiki>[[pix:theme|imagename]]</nowiki>.

For settings I am going to use <nowiki>[[setting:settingname]]</nowiki>, this way it looks a bit like something you are already familiar with.

What we need to decide upon next is the best way in which to replace our settings tag with the settings that the user has set.

There are two immediate options available to us:
# Make the ''csspostprocess'' function do all the work.
# Make the ''csspostprocess'' function call a separate function for each setting.
Solution 1 might sound like the simplest however it is going to result in a '''VERY''' complex function. Remember the user might have left settings blank or entered something that wouldn't be valid so we would need to make the sure there is some validation and a good default.
Because of this I think that solution 2 is the better solution.

So we are going to need a ''csspostprocess'' function and then a function for each of the three settings we have that will do the replacements.
<code php>
// This is our css post process function
function demystified_process_css($css, $theme) {};
// This replaces [[setting:backgroundcolor]] with the background colour
function demystified_set_backgroundcolor($css, $backgroundcolor) {};
// This replaces [[setting:regionwidth]] with the correct region width
function demystified_set_regionwidth() {$css, $regionwidth};
// This replaces [[setting:customcss]] with the custom css
function demystified_set_customcss() {$css, $customcss};
</code>

What you should note about the above functions is that they all start with the theme's name. This is required to ensure that the functions are named uniquely as it is VERY unlikely that someone has already created these functions.

So with our plan set out lets start writing the code.

===Writing the code===
The very first thing that we need to do is create a lib.php for our theme into which our css processing functions are going to go. So please at this point create '''theme/demystified/lib.php''' and open it in your editor ready to go.

The first bit of code we have to write is the function that will be called by Moodle to do the processing '''demystified_process_css'''.

Before we start out please remember that the wonderful thing about coding is that there is any number of solutions to a problem. The solutions that you are seeing here in this tutorial are solutions that I have come up with to meet fulfil the needs of the tutorial without being so complex that they are hard to understand. This probably isn't how I would go about it normally but this is a little easier to understand for those who aren't overly familiar with PHP and object orientation.

====The function: demystified_process_css====

<code php>
function demystified_process_css($css, $theme) {

if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);

if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);

return $css;
}
</code>

So lets look at the things that make up this function:

<code php>
function demystified_process_css($css, $theme) {
//.....
return $css
}
</code>

This of course is the function declaration.

The function gets given two variables, the first '''$css''' is a pile of CSS as one big string, and the second is the theme object '''$theme''' that contains all of the configuration, options, and settings for our theme.

It then returns the ''$css'' variable, essentially returning the modified CSS.

<code php>
//...
if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);
//...
</code>

Here we are processing our first setting ''backgroundcolor''.

The first thing that we need to do is check whether it has been set and whether it has a value. If it has then we store that value in '''$backgroundcolor'''. It is doesn't have a value then we set ''$backgroundcolor'' to null. This ensures that ''$backgroundcolor'' is set because if it isn't then you are going to get a notice (if you have debugging on).

The final line of this block calls the function '''demystified_set_backgroundcolor'''. We haven't written this function yet but we will shortly. When we call it we give it the ''$css'' variable that contains all of the CSS and we give it the background colour variable ''$backgroundcolor''. Once this function is finished it returns the ''$css'' variable with all of the changes made much like how our css processing function works.

What you should also note about this code is this:
<code php>
$theme->settings->backgroundcolor
</code>
As mentioned earlier ''$theme'' is an object that contains all of the configuration and settings for our theme. The ''$theme'' object has a $settings property which contains all of the settings for our theme, and finally the settings property contains a variable backgroundcolor that is the value the user entered for that setting. That is how we get a settings value.

<code php>
if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);
</code>

These two routines are nearly identical to the routine above. For both the regionwidth and the customcss we make sure it has a value and then store it in a variable. We then call the relevant function to make the changes for that setting.

Now that we have the general processing function it is time to write the three functions we have used but not written, ''demystified_set_backgroundcolor'', ''demystified_set_regionwidth'', ''demystified_set_customcss''.

====The function: demystified_set_backgroundcolor====

First up demystified_set_backgroundcolor.

<code php>
/**
* Sets the background colour variable in CSS
*
* @param string $css
* @param mixed $backgroundcolor
* @return string
*/
function demystified_set_backgroundcolor($css, $backgroundcolor) {
$tag = '[[setting:backgroundcolor]]';
$replacement = $backgroundcolor;
if (is_null($replacement)) {
$replacement = '#DDDDDD';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

Ok so what is happening here?

First we need a variable '''$tag''' that contains the tag we are going to replace. As mentioned earlier we are going to use tags that look like the image tags you are already familiar with ''<nowiki>[[setting:settingname]]</nowiki>'', in this case ''<nowiki>[[setting:backgroundcolor]]</nowiki>''.

Next I am going to create a variable called '''$replacement''' into which I put '''$backgroundcolor'''.

The '''IF''' statement that comes next checks ''$replacement'' to make sure it is not null. If it is then we need to set it to a default value. In this case I have used ''#DDD'' as that was the default for the settings.

The line after the IF statement puts it all together. The ''str_replace'' function that we are calling takes three arguments in this order:
# The text to search for.
# The text to replace it with.
# The text to do the replacement in.
It then returns the text with all of the replacements made. So in this case we are replacing the tag with the background colour and it is returning the changed CSS.

The final thing is to return the ''$css'' variable which now contains the correct background colour.

====The function: demystified_set_regionwidth====

Next we have the demystified_set_regionwidth function.
<code php>
/**
* Sets the region width variable in CSS
*
* @param string $css
* @param mixed $regionwidth
* @return string
*/
function demystified_set_regionwidth($css, $regionwidth) {
$tag = '[[setting:regionwidth]]';
$doubletag = '[[setting:regionwidthdouble]]';
$replacement = $regionwidth;
if (is_null($replacement)) {
$replacement = 200;
}
$css = str_replace($tag, $replacement.'px', $css);
$css = str_replace($doubletag, ($replacement*2).'px', $css);
return $css;
}
</code>

This function is very similar to the above function however there is one key thing we are doing different. We are doing two replacements.

# The first replacement is for the width that the user selected. In this case I am replacing the tag ''<nowiki>[[setting:regionwidth]]</nowiki>'' with the width.
# The second replacement is for the width x 2. This is because the page layout requires that the width be doubled for some of the CSS. Here I will replace ''<nowiki>[[setting:regionwidthdouble]]</nowiki>'' with the doubled width.

Remember because it is still just a number we need to add '''px''' to the end of each before we do the replacement.

So the overall process of this function is:
# Define the two tags as '''$tag''' and '''$doubletag'''.
# Make '''$replacement''' the region width ''$regionwidth''.
# Set ''$replacement'' to a default value of 200 is it is null.
# Replace '''<nowiki>[[setting:regionwidth]]</nowiki>''' with the width.
# Replace '''<nowiki>[[setting:regionwidthdouble]]</nowiki>''' with the width x 2.
# Return the changed CSS.

====The function: demystified_set_customcss====

The final function that we need to write is the demystified_set_customcss function.
<code php>
/**
* Sets the custom css variable in CSS
*
* @param string $css
* @param mixed $customcss
* @return string
*/
function demystified_set_customcss($css, $customcss) {
$tag = '[[setting:customcss]]';
$replacement = $customcss;
if (is_null($replacement)) {
$replacement = '';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

This function is just like the first function. I'm going to let you work it out on your own.

And that is it no more PHP... Hallelujah I can hear you yelling. The final thing we need to do is tell our theme about the functions we have written and put the settings tags into the CSS.

===Finishing it all off===

So there are two things we have to do in order to complete this section and have our the settings page implemented and our settings being used.

First we need to tell our theme that we want to use the function ''demystified_process_css'' as the ''csspostprocess'' function. This is done very simply by adding the following line of PHP to the bottom of our theme's config.php file '''theme/demystified/config.php'''.

<code php>
$THEME->csspostprocess = 'demystified_process_css';
</code>

With that done the only thing left is to add the settings tag into the CSS. Remember those settings tags are:

; <nowiki>[[setting:backgroundcolor]]</nowiki> : We need to add this where ever we want the background colour setting to be used.
; <nowiki>[[setting:regionwidth]]</nowiki> : We need to add this where ever we want to set the width of the block regions.
; <nowiki>[[setting:regionwidthdouble]]</nowiki> : We need to add this where ever we want to set the doubled width of the block regions.
; <nowiki>[[setting:customcss]]</nowiki> : We need to add this to the bottom of the CSS file that we want the custom CSS added to.

So lets make those changes in CSS now, open up your ''core.css'' file and replace the CSS with the CSS below:
<code css>
/** Background color is a setting **/
html {background-color:[[setting:backgroundcolor]];}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
/** Override the region width **/
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
/** Custom CSS **/
[[setting:customcss]]
</code>

You will notice that <nowiki>[[setting:backgroundcolor]]</nowiki> has been used for the html tags background colour:
<code css>
html {background-color:[[setting:backgroundcolor]];}
</code>

We have also set the width of the block regions by adding <nowiki>[[setting:regionwidth]]</nowiki> as the width for region-pre and region-post as shown below:
<code css>
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
</code>
You'll notice here that we have to set several different widths and margins using the regionwidth setting and make use of the special regionwidthdouble setting that we added.

The final thing that we did was add the <nowiki>[[setting:customcss]]</nowiki> to the bottom of the file to ensure that the custom CSS comes last (and therefore can override all other CSS).

And with that we are finished. The screenshot below shows how this now looks in the browser if I set the background colour setting to '''<span style='color:#FFA800;'>#FFA800</span>''' and made the column width 240px;

[[Image:Theme.settings.page.04.png|715px|thumb|left|Our settings in action]]<br style="clear:both;" />

==Using the settings within our layout files==
Now that we have utilised the first three settings within our theme's CSS file it is time to implement the other two settings within the layout files so that they are written directly into the page.

You'll be glad to know this is no where near as difficult as utilising settings within a CSS file although it still does require a little bit of PHP.

First up is the logo setting. Into this setting the user is able to enter the URL to an image to use as the logo for the site. In my case I want this to be just a background logo on top of which I want to position the page header.

Before I start there is one thing I need to do however and that is create a default logo background that gets shown if the user hasn't set a specific logo file. To do this I simply created an image '''logo.jpg''' and put it into a pix directory within the demystified theme. You should end up with '''theme/demystified/pix/logo.jpg'''.

Next open up the front-page layout file ''theme/demystified/layout/frontpage.php''. At the top of the file is the PHP that checks what blocks regions the page has and a bit of other stuff. Well right below the existing bit of PHP we want to add the following code:
<code php>
if (!empty($PAGE->theme->settings->logo)) {
$logourl = $PAGE->theme->settings->logo;
} else {
$logourl = $OUTPUT->pix_url('logo', 'theme');
}
</code>
What we are doing here is creating a variable called $logourl that will contain the URL to a logo file that was either entered by the user or if they left it blank is that of our default logo file.

There are two things that you should notice about this. First the logo setting can be retrieved through '''$PAGE->theme->settings->logo''' and second we get the default logo url by calling '''$OUTPUT->pix_url('logo', 'theme')'''.

Now that we have the logo URL we are going to use we need to add an image to the header section of the page as shown below:
<code php>
<div id="page-header" class="clearfix">
<img class="sitelogo" src="<?php echo $logourl;?>" alt="Custom logo here" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
....
</code>

If you save that and browse to your sites front page you will notice that the logo file is now being shown. Hooray. However it is probably not styled too nicely so lets quickly fix that. Open up the core.css file and add the following lines of CSS to the bottom of the file.
<code css>
#page-header {position:relative;min-height:100px;}
#page-header .sitelogo {float:left;}
#page-header .headermain {position:absolute;left:0.5em;top:50px;margin:0;float:none;font-size:40px;}
</code>
These three lines position the image correctly and if you now refresh everything should appear perfectly.

With the logo done the last setting we need to deal with is the footnote setting. The idea with this setting was that the administrator could enter some text into the editor and it would be displayed in the footer of the page.

This is probably the easiest setting to implement.

Within the front page layout file that we edited above add the following lines below those we added previously.

<code php>
if (!empty($PAGE->theme->settings->footnote)) {
$footnote = $PAGE->theme->settings->footnote;
} else {
$footnote = '';
}
</code>

Here we are just collecting the footnote into a variable '''$footnote''' and setting a default footnote comment if the user hasn't entered one.

We can now echo the $footnote variable within the page footer. This can be done as shown below.

<code php>

<div id="page-footer">
<div class="footnote"><?php echo $footnote; ?></div>
<p class="helplink">
<?php echo page_doc_link(get_string('moodledocslink')) ?>
</p>
</code>

And with that done we are finished! Congratulations if you got this far.

The screenshot below shows the demystified theme we have just created that is styled by the settings page.

[[Image:Theme.settings.page.05.png|715px|thumb|left|My finished demystified theme]]<br style="clear:both" />

==Testing our creation==
Congratulations to you! If you've made it this far you have done very well. Now it is time to have a look at what we have created and give it a quick test run.

So in this tutorial we have achieved the following:

* We created a theme called demystified that is based on the standard theme.
* We added a settings page to our new theme.
* We added the following settings to our settings page:
** We can set a background colour through the admin interface.
** We can change the logo of the site.
** We can change the block region width.
** We can add a footnote to the page footer
** We can add some custom CSS to seal the deal.
* Those settings were then used in the CSS files for our theme.
* They were also used in the layout files for our theme.
* And here we are testing it all.

The screenshots below show my testing process and I change each setting and view the outcome. The great thing about this is that with theme designer mode on you see the changes as soon as the form refreshes.

[[Image:Theme.settings.page.06.png|300px|thumb|left|Default settings]]
[[Image:Theme.settings.page.07.png|300px|thumb|left|Changed the background colour setting]]
[[Image:Theme.settings.page.08.png|300px|thumb|left|Changed the logo and region width]]
[[Image:Theme.settings.page.09.png|300px|thumb|left|Added a footnote]]
[[Image:Theme.settings.page.10.png|300px|thumb|left|Added some custom CSS]]
<br style="clear:both" />

==The different settings you can use==
During this tutorial we use four different kinds of settings, a text box, text area, a select (dropdown) and the editor however as I'm sure you have all guessed there is many more some of which will certainly be useful for theme settings.

The following are examples of some of the different settings. I should add that these build upon what we have already done within the tutorial but are not included in the download.

===Colour picker===
[[Image:Theme.settings.page.11.png|400px|thumb|The colour picker]]
I can hear you all asking now 'Why didn't you mention this one earlier?' well the answer is simple it didn't exist when I first wrote the tutorial. It is an admin setting that I wrote several days after because of the fantastic effort people were putting into trying out settings pages.

A bit about the colour picker. First up it is a text box that when the page loads turns into a colour picker that can be used to select a colour and can even preview the selected colour in the page (by clicking the preview button). It is designed to be very easy to use and the code is just about as simple as creating a normal text box setting.

In the image to the left I have replaced the background colour setting we created during the tutorial with the colour picker. Lets have a look at the code involved for that.
<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$previewconfig = array('selector'=>'html', 'style'=>'backgroundColor');
$setting = new admin_setting_configcolourpicker($name, $title, $description, $default, $previewconfig);
$temp->add($setting);
</code>
So first thing you should notice is that the first four lines of code have not changed at all!

The first change we have is to create a variable '''$previewconfig'''.
This variable is used to tell the colour picker what to do when the user clicks the preview button. It should be an array that contains two things, first a selector, and second a style.
# The selector is a CSS selector like ''.page .header h2''.
# The style is a what should change, there are two immediate values it can be, either '''backgroundColor''' or '''color'''.
In my case the selector is '''html''' to target the html tag and the style is backgroundColor to change the background colour.

The second change is to use '''admin_setting_configcolourpicker''' instead of ''admin_setting_configtext''. The arguments are nearly identical as well except that there is an extra argument to which we give the '''$previewconfig''' variable.

And that is it! it is all you need to get the colour picker up and running.

'''Extra note:''' The $previewconfig variable is optional. If you don't want a preview button the simply set ''$previewconfig = null''

==Common pitfalls and useful notes==

This section is really just a collection of pointers, tips, notes, and other short useful stuff that may be of use to those attempting this tutorial.

# First up and most importantly there are very few limitations to what you achieve in this fashion.
# If you get stuck or need a hand ask in the forums, there's always someone round who can help.
# If you do something really cool let us know, I know everyone in the community loves finding our what others are achieving.
# You don't have to use ''admin_settingpage'' you can also use '''admin_externalpage''' if you prefer. It should be noted however that it is not the preferred way to do it as admin_externalpage's were only left in Moodle 2.0 for backwards compatibility (although they are more flexible one day they will be deprecated or removed). Thank you to Darryl for raising this.
# If you find that your language strings aren't being used (you are getting language string notices) and you have double checked that you have turned '''langstringcache''' off then you may need to delete the language cache directory. This is located in the moodledata directory for you installation: moodledata/cache/lang/*. You should delete the directory for your chosen language by default ''en''.

==More information==
* [[Themes 2.0]]
* [[Themes 2.0 creating your first theme]]
* [[Themes 2.0 overriding a renderer]]
* [[Themes_2.0 adding upgrade code]]
* [[Styling and customising the dock]]
* http://moodle.org/mod/forum/discuss.php?d=152053

Database

2011-02-14T14:11:35Z

Mattgibson: Added bit about pluralised table names

==Database structures==

To help you create tables that meet these guidelines, we recommend you use the built in [[XMLDB_defining_an_XML_structure#The_XMLDB_editor|database definition (XMLDB) editor]].

# Every table must have an auto-incrementing id field (INT10) as primary key. (see [[IdColumnReasons]])
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:
#* id - as described above
#* course - the id of the course that each instance belongs to
#* name - the full name of each instance of the module
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).
# Core tables in general should have single word names non-pluralised, and double word names pluralised only for the last letter e.g. 'course', 'course_categories'. The only exceptions should be for reserved words e.g. 'files'. Some tables don't fit this pattern right now for historical reasons, but this will eventually be changed.
# Table and column names should avoid using [[Database reserved words|reserved words in any database]]. Please check them before creation. Table names may be up to 28 characters long, and Column names up to 30 characters.
# Column names should be always lowercase, simple and short, following the same rules as for variable names.
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.
# Always define a default value for each field (and make it sensible)
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.
# In order to guarantee [[XMLDB problems#Table and column aliases - the AS keyword|cross-db compatibility]] follow these simple rules about the use of the '''AS''' keyword (only if you need table/column aliases, of course):
#* '''Don't use''' the '''AS''' keyword for '''table aliases'''.
#* '''Do use''' the '''AS''' keyword for '''column aliases'''.
# '''Never''' create UNIQUE KEYs (constraints) at all. Instead use UNIQUE INDEXes. In the future, if we decide to add referential integrity to Moodle and we need UNIQUE KEYs they will be used, but not now. Please note that the XMLDB editor allows you to specify both XMLDB-only UNIQUE and FOREIGN constraints (and that's good, in order to have the XML well defined) but only underlying INDEXes will be generated.
# Those XMLDB-only UNIQUE KEYs (read previous point) only must be defined if such field/fields '''are going to be the target''' for some (XMLDB-only too) FOREIGN KEY. Else, create them as simple UNIQUE INDEXes.
# Tables associated '''with one block''' must follow this convention with their names: '''$CFG->prefix + "block_" + name_of_the_block + anything_else'''. For example, assuming that $CFG->prefix is 'mdl_', all the tables for the block "rss_client" must start by 'mdl_block_rss_client' (being possible to add more words at the end, i.e. 'mdl_block_rss_client_anothertable'...). This rule will be 100% enforced with Moodle 2.0, giving time to developers until then. See [http://tracker.moodle.org/browse/MDL-6786 Task 6786] for more info about this.
# '''Never''' make database changes in the STABLE branches. If we did, then users upgrading from one stable version to the next would have duplicate changes occurring, which may cause serious errors.
# When refering to integer variable in SQL queries, do not surround the value in quotes. For example, get_records_select('question', "category=$catid") is right. get_records_select('question', "category='$catid'") is wrong. It hides bugs where $catid is undefined. ([http://moodle.org/mod/forum/discuss.php?d=80629 This thread explains].)

[[Category:Coding guidelines|Database]]
[[Category:DB|Database]]
[[Category:XMLDB|Database]]

DB layer 2.0 migration docs

2011-02-08T16:23:22Z

Mattgibson: /* The golden changes */

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

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

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

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

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

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

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

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

__TOC__

== check_db_syntax: One helper script ==

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

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

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

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

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

== XMLDB/DDL changes ==

=== Some comments ===

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

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

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

global $CFG, $THEME, $DB;
</code>
* All upgrade.php scripts must NOT have '''$db''' (lowercase) in the globals declaration. Delete it if present.
* After the global declaration in the points above, this line must be present (we'll need it later):
<code php>
$dbman = $DB->get_manager(); /// loads ddl manager and xmldb classes
</code>
* All '''XMLDBTable''' instances in your upgrade code must be replaced by '''xmldb_table''' (no change in parameters)
* All '''XMLDBField''' instances in your upgrade code must be replaced by '''xmldb_field''' (with change in params, both $enum and $enumvalues are out from function declaration!)
* All '''XMLDBIndex''' instances in your upgrade code must be replaced by '''xmldb_index''' (no change in parameters)
* All '''XMLDBKey''' instances in your upgrade code must be replaced by '''xmldb_key''' (no change in parameters)
* All the '''addFieldInfo()''' methods must be replaced by '''add_field()''' (with change in params, both $enum and $enumvalues (the 7th and 8th parameters) are out from function declaration!)
* All the '''addIndexInfo()''' methods must be replaced by '''add_index()''' (no change in parameters)
* All the '''addKeyInfo()''' methods must be replaced by '''add_key()''' (no change in parameters)
* All the '''setAttributes()''' methods must be replaced by '''set_attributes()''' (with change in params, both $enum and $enumvalues (the 6th and 7th parameters) are out from function declaration!)
* All the DDL functions used in your upgrade code must be transformed as detailed below (it's simply about adding '''"$dbman->"''' - without the quotes - before each function call). No changes in parameters are required:
** table_exists ==> $dbman->table_exists
** field_exists ==> $dbman->field_exists
** index_exists ==> $dbman->index_exists
** find_index_name ==> $dbman->find_index_name
** find_check_constraint_name ==> $dbman->find_check_constraint_name ('''DEPRECATED in 2.0. OUT in 2.1''')
** check_constraint_exists ==> $dbman->check_constraint_exists ('''DEPRECATED in 2.0. OUT in 2.1''')
** find_sequence_name ==> '''OUT in 2.0''', see MDL-20349
** create_table ==> $dbman->create_table
** drop_table ==> $dbman->drop_table
** rename_table ==> $dbman->rename_table
** add_field ==> $dbman->add_field
** drop_field ==> $dbman->drop field
** rename_field ==> $dbman->rename_field
** change_field_type ==> $dbman->change_field_type
** change_field_precision => $dbman->change_field_precision
** change_field_unsigned ==> $dbman->change_field_unsigned
** change_field_notnull ==> $dbman->change_field_notnull
** change_field_enum ==> $dbman->change_field_enum ('''OUT in 2.0''', see '''[[DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' to get rid of remaining ENUMs in code).
** change_field_default ==> $dbman->change_field_default
** add_key ==> $dbman->add_key
** drop_key ==> $dbman->drop_key
** add_index ==> $dbman->add_index
** drop_index ==> $dbman->drop_index
* The DDL functions that change things (create/drop/rename/add)_(table/field/index) no longer return boolean. Instead, they throw an exception if they fail. So your upgrade.php no longer needs to use a '''$result''' variable, and instead should use the '''upgrade_mod_savepoint()''' function:
<code php>/** old way **/
if ($result && $oldversion < 2008061000) {
$table = new xmldb_table('facetoface_submissions');
$field = new xmldb_field('notificationtype');
$field->set_attributes(XMLDB_TYPE_INTEGER, '10', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'timemodified');

$result = $result && $dbman->add_field($table, $field);
}

/** new way **/
if ($oldversion < 2008061000) {
$table = new xmldb_table('facetoface_submissions');
$field = new xmldb_field('notificationtype');
$field->set_attributes(XMLDB_TYPE_INTEGER, '10', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'timemodified');

$dbman->add_field($table, $field);
upgrade_mod_savepoint(true, 2008061000, 'facetoface');
}</code>

* Finally, and not less important, your code (module, block... plugin) must guarantee that it can be upgraded '''ONLY''' from Moodle 1.9, so any previous upgrade code can be safely deleted. '''Moodle 2.0 requires Moodle 1.9''' to be upgraded, so everybody will run the 1.9 => 2.0 upgrade (with other paths like 1.8 => 2.0 not being possible). This is a good time to clean-up your upgrade code a bit ;-). Don't forget to take a look at the [[XMLDB editor|XMLDB Editor]] and the core modules to see how [http://cvs.moodle.org/moodle/lib/db/upgrade.php?view=markup upgrade.php] files should look in Moodle 2.0.

== DML changes ==

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

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

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

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

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

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

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

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

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

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

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

* <span id="g2"><b>G2</b></span>: All uses of addslashes() '''must be removed'''. They are no longer needed

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

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

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

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

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

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

* <span id="g5"><b>G5</b></span>: Placeholders must be used for table names. Instead of {$CFG->prefix}tablename, use {tablename}.

<code php>
Example:

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

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

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

<code php>
Examples:

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

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

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

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

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

<code php>
Example:

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

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

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

=== The iron changes ===

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

<code php>
Example:

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

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

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

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

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

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

* <span id="g1"><b>T2</b></span>: Originally DML functions were returning ''false'' if error occurred - ''dml_exception'' is thrown now instead.
<code php>
Example:

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

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

== See also ==

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

Enrolment plugins

2010-11-09T13:44:26Z

Mattgibson: /* How to write an Enrolment plugin in Moodle 1.9 */ Added warning over PARAM_ALPHA for plugin names

==How to write an Enrolment plugin in Moodle 1.9==

Create a new directory called <code>/enrol/</code>'''<code>PLUGINNAME</code>'''. Within this directory, create a file <code>/enrol/</code>'''<code>PLUGINNAME</code>'''<code>/enrol.php</code> which contains the declaration for a class called <code>enrolment_plugin_</code>'''<code>PLUGINNAME</code>'''. Note that PLUGINNAME must be letters only as it is passed through PARAM_ALPHA.

<code php>
class enrolment_plugin_PLUGINNAME {
// Functions go here
// ...
}
</code>

=== Mandatory functions ===

Your enrolment plugin class is required to define these two functions, which print and process a configuration form.

<code php>
/**
* Prints out the configuration form for this plugin. All we need
* to provide is the form fields. The <form> tags and submit button will
* be provided for us by Moodle.
*
* @param object $formdata Equal to the global $CFG variable, or if
* process_config() returned false, the form contents
* @return void
*/
public function config_form( $formdata ){
return;
}

/**
* Process the data from the configuration form.
*
* @param object $formdata
* @return boolean True if configuration was successful, False if the user
* should be kicked back to config_form() again.
*/
public function process_config( $formdata ){
return true;
}
</code>

=== Optional functions ===

==== Automated enrolment ====

To handle automated enrolment, your function may contain a <code>setup_enrolments($user)</code> function. This will be called each time a user logs in, to allow the plugin to make any changes to their enrolments.

<code php>
/**
* OPTIONAL: Set up non-interactive enrolments for user. This is the most
* important function for non-interactive enrolment plugins (such as LDAP
* and external database). It is called each time a user logs in.
*
* @param object $user
* @return void
*/
public function setup_enrolments( $user ){
// Note that when you're setting up role assignments, you should use the
// mdl_role_assignment.enrol column to indicate which role assignments
// are from this plugin.
role_assign($someroleid, $user->id, null, $somecontextid, 0, 0, 0, 'PLUGINNAME');
role_unassign($someroleid, $user->id, null, $somecontextid, 'PLUGINNAME');

return;
}
</code>

==== Interactive enrolment ====

Your plugin can handle interactive enrolment (i.e. self-enrolment) by implementing these four functions. (See the manual enrolment plugin <code>enrol/manual/enrol.php</code> for an example that uses all of these.)

<code php>
/**
* OPTIONAL: Prints the entry form/page for interactive enrolment into a course.
*
* This is only called from course/enrol.php. Most plugins will probably
* override this to print payment forms, etc, or even just a notice to say
* that manual enrollment is disabled.
*
* @param object $course
* @return void
*/
public function print_entry(){
}

/**
* OPTIONAL: The other half to print_entry(), this checks the form data.
*
* This function checks that the user has completed the task on the enrollment
* entry page and enrolls them.
*
* @param object $form
* @param object $course
* @return void
*/
public function check_entry( $form, $course ){
// some logic
// some role_assign();
}

/**
* OPTIONAL: Check if the given enrolment key matches a group enrolment key for
* the given course.
*
* @param int $courseid
* @param string $enrolmentkey
* @return mixed The group id of the group which the key matches, or false
* if it matches none
*/
public function check_group_entry( $courseid, $password ){
// some logic
if ( $itlooksgood ){
return $groupid;
} else {
return false;
}
}

/**
* OPTIONAL: Return a string with icons that give enrolment information
* for this course.
*
* @param object $course
* @return string
*/
public function get_access_icons( $course ){
return 'put icons here';
}
</code>

==== Cron ====

Your plugin can perform cron tasks if it contains a <code>cron()</code> function:

<code php>
/**
* OPTIONAL: If this function exists, it will be called each time
* admin/cron.php runs. It takes no arguments and returns no values,
* but anything written to $this->log will be printed to the cron output.
*
* @return void
*/
public function cron(){
$this->log = 'Print this in the cron log!';
}
</code>

=== Language Strings ===

Create a lang directory and file under your plugin's directory, like this '''<code>enrol/PLUGINNAME/lang/en_utf8/enrol_PLUGINNAME.php</code>'''. Plugins are expected to provide at least these two strings:

<code php><?php

// The name of your plugin. Displayed on admin menus.
$string['enrolname'] = 'My plugin';

// Description of your plugin. Shown on the plugin's configuration screen.
$string['description'] = 'This is what my plugin does.';

?></code>

Those two strings will be accessed automatically by Moodle in various situations. You can (and should) of course include other [[Places to search for lang strings|language strings]] in your plugin's lang file(s). These can be accessed like normal language strings, using "enrol_PLUGINNAME" as the module name, e.g. <code>get_string('anotherstring', 'enrol_PLUGINNAME')</code>.

=== Database ===

If your plugin needs to have its own Moodle database tables, create a file called <code>enrol/PLUGINNAME/version.php</code> like this:

<code php><?php
$plugin->version = 2010091600; // Version of your plugin
$plugin->requires = 2007101000; // Required Moodle version (from /version.php)
?></code>

Then create a directory <code>enrol/PLUGINNAME/db</code>, and use the [[XMLDB editor]] to set up your tables.

==Testing paypal using the paypal developer sandbox==

=== For moodle 1.4 - 1.8 ===

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* change the address being used to send data to paypal to use the sandbox. in enrol/paypal/enrol.html:
** change the form post action to be https://www.sandbox.paypal.com/cgi-bin/webscr instead of https://www.paypal.com/cgi-bin/webscr
* change the address that is used to check the acknowledgment from paypal. in enrol/paypal/ipn.php, change:
** $fp = fsockopen ('www.paypal.com', 80, $errno, $errstr, 30);
* to
** $fp = fsockopen ('www.sandbox.paypal.com', 80, $errno, $errstr, 30);
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.

=== For moodle 1.8.2 - 1.9.x ===

The above changes to the code were made part of the release starting with version 1.8.2

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.
* add the following line to config.php located in the root directory of your installation (where you installed Moodle).
** $CFG->usepaypalsandbox = 'TRUE';
* Add the business account email address from "business" account you created to the paypal module settings (in 1.9.x - Site Administration>Courses>Enrolments>Paypal>Edit)
* You should be ready to test
* When finished be sure to remove the line that was added to config.php in your root directory.

=== Note about Paypal Sandbox ===

Only implement these changes if the above is not working and Moodle is returning the "...Unfortunately your payment..." message after returning from Paypal Sandbox.

At the time of this writing (14 June 2008) some changes are necessary to test successfully in the Paypal Sandbox. Details can be found [http://www.pdncommunity.com/pdn/board/message?board.id=sandbox&view=by_date_ascending&message.id=9802#M9802 here]. This could change at any time at which point this may become unnecessary. For now do the following (only tested in 1.9.x so far):

* Locate ipn.php in your installation on your server by migrating to to ../enrol/paypal/ipn.php
* Create a backup copy of ipn.php and give it a name something like ipn.php-backup
* Return to ipn.php and locate the following code :<br />
$header = '';<br />
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n";<br />
$header .= "Content-Type: application/x-www-form-urlencoded\r\n";<br />
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n";<br />
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'www.sandbox.paypal.com';<br />
$fp = fsockopen ($paypaladdr, 80, $errno, $errstr, 30);
* Change that code to :<br />
$header = '';<br />
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n";<br />
$header .= "Content-Type: application/x-www-form-urlencoded\r\n";<br />
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n";<br />
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'ssl://www.sandbox.paypal.com';<br />
$fp = fsockopen ($paypaladdr, 443, $errno, $errstr, 30);<br />
* Try the course purchase again.

If the above still is not working you will need to seek help in the [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] Forum.

==Enrolment plugins 1.7==

===Background===
# isteacher(), isstudent(), isadmin(), iscoursecreator() are all deprecated and should be replaced with checks on has_capability instead.
# enrol_student() and add_teacher() are obsolete, so use the generic role_assign() or the convenience function for "students" called enrol_into_course() instead.
# unenrol_student() and remove_teacher() are obsolete, so use the generic role_unassign() instead.
# All the roles have a "shortname", so by default we can refer to them using "teacher", "student", "editingteacher" etc. Note that new roles may have different names. Enrolment plugins can use these to map outside data onto the inside roles without needing to know internal role id numbers. For example, it would be really handy for the flatfile plugin to refer to roles directly like this.
# Each plugin used to implement get_student_courses() and get_teacher_courses() for use at login time. These now need to be converted to one new function called $enrol->setup_enrolments($user) which looks up sets all enrolments for a given user (using role_assign and role_unassign).
# All the session arrays like $USER->student[] and $USER->teacher[] are gone and should not be relied on. You can check what roles a user already has by calling get_user_roles() on that course context.

===What's been done===

#enrol/manual has been converted to use the new functions
#enrol/imsenterprise has been converted - testing needed though

===What still needs to be done===

#enrol/authorize
#enrol/database
#enrol/flatfile
#enrol/ldap
#enrol/paypal

==See also==
*[[Enrolment plugins|Enrolment plugins (administrator)]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Enrolment plugins]]
[[Category:Enrolment]]

Setting up Netbeans

2010-06-06T19:53:04Z

Mattgibson: /* Checkout of contrib code */ Added symlink tip

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest [http://netbeans.org/community/releases/68/ 6.8 version] with PHP support, only 25 MB.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

As far as I can tell, there is no way to get NetBeans to work with CVS keys on Mac/Linux via the system SSH binary, so you will ned to use the internal SSH and your password (which you can choose to save).

If you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

====Checkout of main Moodle codebase====

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

====Checkout of contrib code====

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'. Note that you should not try to specify the full contrib repository path yet.
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

Note that the last three points may cause you some grief when attempting to commit changes. CVS doesn't seem to like having subfolders with different origins. A workaround that operates well for me is to check out the contrib code manually into a folder using the command line as specified in the CVS for developers instructions, then import that code as a new project with existing sources. This allows easy commits and updates, whilst keeping it separate. You can then make a symlink from you main Moodle project to your contrib directory, restart NetBeans (the CVS info and symlink stuff is only refreshed on restart) and then right click the linked directory and choose 'Ignore', then do the same and choose 'Exclude from commit'. You can now use the code as if it were part of Moodle, still getting all the code completion stuff, and also do clean updates and commits from the secondary project. [[User:Matt Gibson|Matt Gibson]] 19:53, 6 June 2010 (UTC)

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. <br/>In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)

<p class="note">
Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)
</p>

== Optimization ==

1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within netbeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to Tools->plugins->available plugins and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:NetBeans]]
[[Category:Developer tools|NetBeans]]

Setting up Netbeans

2010-06-05T13:21:25Z

Mattgibson: /* Checkout for developers with write access */

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest [http://netbeans.org/community/releases/68/ 6.8 version] with PHP support, only 25 MB.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

As far as I can tell, there is no way to get NetBeans to work with CVS keys on Mac/Linux via the system SSH binary, so you will ned to use the internal SSH and your password (which you can choose to save).

If you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

====Checkout of main Moodle codebase====

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

====Checkout of contrib code====

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'. Note that you should not try to specify the full contrib repository path yet.
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. <br/>In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)

<p class="note">
Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)
</p>

== Optimization ==

1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within netbeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to Tools->plugins->available plugins and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:NetBeans]]
[[Category:Developer tools|NetBeans]]

Setting up Netbeans

2010-06-05T13:17:31Z

Mattgibson: /* Checkout for developers with write access */

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest [http://netbeans.org/community/releases/68/ 6.8 version] with PHP support, only 25 MB.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

IF you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

====Checkout of main Moodle codebase====

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

====Checkout of contrib code====

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'. Note that you should not try to specify the full contrib repository path yet.
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. <br/>In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)

<p class="note">
Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)
</p>

== Optimization ==

1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within netbeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to Tools->plugins->available plugins and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:NetBeans]]
[[Category:Developer tools|NetBeans]]

Setting up Netbeans

2010-06-05T13:14:30Z

Mattgibson: /* Checkout for developers with write access */

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest [http://netbeans.org/community/releases/68/ 6.8 version] with PHP support, only 25 MB.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

IF you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. <br/>In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)

<p class="note">
Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)
</p>

== Optimization ==

1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within netbeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to Tools->plugins->available plugins and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:NetBeans]]
[[Category:Developer tools|NetBeans]]

Migrating contrib code to 2.0

2010-05-18T16:25:02Z

Mattgibson:

{{Moodle 2.0}}

<p class="note">WARNING: Under construction RIGHT NOW!</p>

The goal of this page is to provide a checklist of tasks to be considered to upgrade CONTRIB code to Moodle 2.0. Several significant changes have taken place including the File API, DB Layer, Navigation, Output renderer, etc. It would be good if we had a list that contributors could follow to help move them toward being able to migrate the code. Any help in building up this list is greatly appreciated.

''Please add useful links...''

* [[DB_layer_2.0_migration_docs]]
* [[Using the File API in Moodle forms]]
* [[Output_renderers]]
* [[Migrating_your_code_to_the_2.0_rendering_API]] (n.b., some info outdated and may need updating)
* [[Themes_2.0]]

Some details of how to re-design image CSS for plugin code ar in the main themes documentation: [[Themes_2.0_creating_your_first_theme#Using_images_within_CSS]]

Be aware that themes are now cached on the server and so emptying your browser cache will not refresh the CSS. This can only be done by going to the site administration->appearance->themes->theme selector page and clicking the 'invalidate theme caches' button.

Javascript is included in different ways now and will need to be migrated, see the PHPDoc comments in /lib/outputrequirements.lib and some (slightly outdated) advice here: [[JavaScript_guidelines]]

==See also==

* CONTRIB-1988
* http://cvs.moodle.org/moodle/blocks/upgrade.txt?view=markup
* http://cvs.moodle.org/moodle/mod/upgrade.txt?view=markup

Migrating contrib code to 2.0

2010-05-18T16:22:11Z

Mattgibson:

{{Moodle 2.0}}

<p class="note">WARNING: Under construction RIGHT NOW!</p>

The goal of this page is to provide a checklist of tasks to be considered to upgrade CONTRIB code to Moodle 2.0. Several significant changes have taken place including the File API, DB Layer, Navigation, Output renderer, etc. It would be good if we had a list that contributors could follow to help move them toward being able to migrate the code. Any help in building up this list is greatly appreciated.

''Please add useful links...''

* [[DB_layer_2.0_migration_docs]]
* [[Using the File API in Moodle forms]]
* [[Output_renderers]]
* [[Migrating_your_code_to_the_2.0_rendering_API]] (n.b., some info outdated and may need updating)
* [[Themes_2.0]]

Some details of how to re-design image CSS for plugin code ar in the main themes documentation: [[Themes_2.0_creating_your_first_theme#Using_images_within_CSS]]

Javascript is included in different ways now and will need to be migrated, see the PHPDoc comments in /lib/outputrequirements.lib and some (slightly outdated) advice here: [[JavaScript_guidelines]]

==See also==

* CONTRIB-1988
* http://cvs.moodle.org/moodle/blocks/upgrade.txt?view=markup
* http://cvs.moodle.org/moodle/mod/upgrade.txt?view=markup

DB layer 2.0 migration docs

2010-05-03T21:21:49Z

Mattgibson: /* The golden changes */ Added note on how to combine G6 and G7

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

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

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

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

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

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

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

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

__TOC__

== check_db_syntax: One helper script ==

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

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

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

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

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

== XMLDB/DDL changes ==

=== Some comments ===

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

=== The changes ===

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

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

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

== DML changes ==

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

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

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

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

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

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

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

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

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

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

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

* <span id="g2"><b>G2</b></span>: All uses of addslashes() '''must be removed'''. They are no longer needed

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

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

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

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

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

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

* <span id="g5"><b>G5</b></span>: Placeholders must be used for table names. Instead of {$CFG->prefix}tablename, use {tablename}.

<code php>
Example:

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

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

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

<code php>
Examples:

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

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

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

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

<code php>
Example:

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

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

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

=== The iron changes ===

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

<code php>
Example:

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

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

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

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

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

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

* <span id="g1"><b>T2</b></span>: Originally DML functions were returning ''false'' if error occurred - ''dml_exception'' is thrown now instead.
<code php>
Example:

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

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

== See also ==

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

SSH key

2010-04-25T21:13:24Z

Mattgibson: /* Mac OS X */

==What is a SSH key?==

SSH keys are used for secure connections across a network. They come in pairs, so you have a public key and a private key.

The standard ssh2 file format (see
http://www.openssh.org/txt/draft-ietf-secsh-publickeyfile-02.txt)
looks like this:

---- BEGIN SSH2 PUBLIC KEY ----
Comment: "jtbell@Jon-Bells-Computer"
AAAAB3NzaC1kc3MAAACBAPNgmidbM2rhYjUXunpnlXjHWfV+vc8/5YKrn8Y5P0Y6KwmG2G
GMgNBon3LX3iJlBhtuU3FCBj3G1Kdt5vUhQHhUmHVrOasi47vawTrv7ZJCfiaSGwRsiBHt
Jta5CAp7t0EnzX2q6BvPbFBBHNLyy6uNVpL2jOR06Pkx/vaqyScvAAAAFQDHvwmjWYwK9g
K6Sp+pSvI7bwEUtwAAAIANMJDotMpfj89N+7+FJylSS+uFEQSS61PxENl/Mcj1jUREjJg2
eNsJdAB9Ev99hWYS+7lFRtTJ2eh4Y9gpGe7BX3e2YGHOqp8cWCVCIKaMzwk9To+xnfThWq
IfHT8I6CJxp/5ez02m6F2k/5iukvOwbGms6EAZK1DTBhDOHjEQwQAAAIAlz2/qBWkaMP+s
W8FLmGKM+cCw5+asOaJGTwrFVuwJkDMvdEWxmG92A2dxuUske0d/AkN6zJp7HD0wlfesRM
3+c+Res5qun9lFcdM4i03VoV5mXd+T7laS8yku6vZgvZZFnPvr2LOUnc7XThGFwMaQpFEW
U8cvQbttO6QrT2CD2w==
---- END SSH2 PUBLIC KEY ----

However, Moodle uses OpenSSH on its server and this key will not work with the OpenSSH server in this format; OpenSSH requires the key to be in OpenSSH format. Here is an example of a DSA public key in OpenSSH format (usually they are all in one line):

ssh-dss AAAAB3NzaC1kc3MAAACBAJ3hB5SAF6mBXPlZlRoJEZi0KSIN+NU2iGiaXZXi9CDrgVxTp6/
sc56UcYCp4qjfrZ2G3+6PWbxYso4P4YyUC+61RU5KPy4EcTJske3O+aNvec/20cW7PT3TvH1+sxwGry
mD50kTiXDgo5nXdqFvibgM61WW2DGTKlEUsZys0njRAAAAFQDs7ukaTGJlZdeznwFUAttTH9LrwwAAA
IAMm4sLCdvvBx9WPkvWDX0OIXSteCYckiQxesOfPvz26FfYxuTG/2dljDlalC+kYG05C1NEcmZWSNES
GBGfccSYSfI3Y5ahSVUhOC2LMO3JNjVyYUnOM/iyhzrnRfQoWO9GFMaugq0jBMlhZA4UO26yJqJ+BtX
IyItaEEJdc/ghIwAAAIBFeCZynstlbBjP648+mDKIvzNSS+JYr5klGxS3q8A56NPcYhDMxGn7h1DKbb
2AV4pO6y+6hDrWo3UT4dLVuzK01trwp PYp6JXTSZZ12ZaXNPz7sX9/z6pzMqhX4UEfjVsLcuF+ZS6a
QCPO0ZZEa1z+EEIZSD/ykLQsDwPxGjPBqw== someone@somewhere.com

In addition to OpenSSH and Standard SSH formats there are a variety of proprietary formats as well as SSH1 and SSH2 differences to account for, which can make this confusing.

In the example above you will note that the key starts with "ssh-dss". This is because this key was generated using DSA as opposed to RSA. A number of vendors in the SSH arena have argued, as per the PuTTY documentation that can be found at http://the.earth.li/~sgtatham/putty/0.55/htmldoc/Chapter8.html#S8.2.10 that users should employ RSA encryption because

DSA has an intrinsic weakness which makes it very easy to create a signature
which contains enough information to give away the private key! This would
allow an attacker to pretend to be you for any number of future sessions.

An SSH2 public key in OpenSSH format will start with "ssh-rsa".

The idea behind all of this is that once you have keys on the remote server and your local host, access will be simpler since the server will only grant access to someone who has the matching private key.

==Why do I need a SSH key?==

Our CVS server uses OpenSSH, so if you are a Moodle developer and you want to make your logins easier (by avoiding typing in your password all the time) then you will need to submit public key in Openssh format via the "Update my developer information" tab at http://moodle.org/cvs.

==How do I create a SSH key pair?==

===Platform Independent===

Visit http://www.sshkeygen.com and simply follow the directions there.

===Eclipse===

If you plan to use Eclipse for development, please refer to the Eclipse document https://docs.moodle.org/en/Eclipse as Eclipse now has a plugin that allows you to manage all ssh key matters from within Eclipse.

===Unix/Linux===

You can use ssh-keygen at your system prompt. Please consult the man page on your system for the options available to you.

# Run: '''ssh-keygen -t (rsa or dsa)'''. This will not include a passphrase. *
# Use of rsa or dsa above will result in rsa or dsa replacing each XXX below.
# Look in your ~/.ssh directory (or wherever you saved the output). You'll find '''id_XXX''' (private) and '''id_XXX.pub''' (public).
# Cut and paste the contents of '''id_XXX.pub''' into your developer profile on http://moodle.org/cvs
# Put the private key wherever you will be calling CVS from (in your .ssh directory, for example). Make sure it's secure!

* This section initially recommended using ''ssh-keygen -d'' but it is unclear what the source of this -d option might be.

===Windows===
Use puttygen and follow the instructions [http://the.earth.li/~sgtatham/putty/0.58/htmldoc/Chapter8.html here]. Make sure you choose the RSA2 key format and that when you copy the key data into the textbox on the site, that you have all of the characters on one line. If you have opened the key with word pad, it will have line breaks in it which will stop it from working.

The box should look like this:

ssh-rsa
AAAAWfg&jkf4D34H5@4svf..... (single very long line continues beyond edge of textbox)

===Mac OS X===
If you have an existing key in Putty format, open it in puttygen on windows and then choose conversions and export as openssh format. You can then import the key into OS X using
ssh-add -K filename
The -K flag is optional and stores your passphrase in the keychain [http://developer.apple.com/mac/library/documentation/Darwin/Reference/ManPages/man1/ssh-add.1.html ssh-add documentation]

SSH key

2010-04-25T21:10:48Z

Mattgibson: /* Mac OS X */

==What is a SSH key?==

SSH keys are used for secure connections across a network. They come in pairs, so you have a public key and a private key.

The standard ssh2 file format (see
http://www.openssh.org/txt/draft-ietf-secsh-publickeyfile-02.txt)
looks like this:

---- BEGIN SSH2 PUBLIC KEY ----
Comment: "jtbell@Jon-Bells-Computer"
AAAAB3NzaC1kc3MAAACBAPNgmidbM2rhYjUXunpnlXjHWfV+vc8/5YKrn8Y5P0Y6KwmG2G
GMgNBon3LX3iJlBhtuU3FCBj3G1Kdt5vUhQHhUmHVrOasi47vawTrv7ZJCfiaSGwRsiBHt
Jta5CAp7t0EnzX2q6BvPbFBBHNLyy6uNVpL2jOR06Pkx/vaqyScvAAAAFQDHvwmjWYwK9g
K6Sp+pSvI7bwEUtwAAAIANMJDotMpfj89N+7+FJylSS+uFEQSS61PxENl/Mcj1jUREjJg2
eNsJdAB9Ev99hWYS+7lFRtTJ2eh4Y9gpGe7BX3e2YGHOqp8cWCVCIKaMzwk9To+xnfThWq
IfHT8I6CJxp/5ez02m6F2k/5iukvOwbGms6EAZK1DTBhDOHjEQwQAAAIAlz2/qBWkaMP+s
W8FLmGKM+cCw5+asOaJGTwrFVuwJkDMvdEWxmG92A2dxuUske0d/AkN6zJp7HD0wlfesRM
3+c+Res5qun9lFcdM4i03VoV5mXd+T7laS8yku6vZgvZZFnPvr2LOUnc7XThGFwMaQpFEW
U8cvQbttO6QrT2CD2w==
---- END SSH2 PUBLIC KEY ----

However, Moodle uses OpenSSH on its server and this key will not work with the OpenSSH server in this format; OpenSSH requires the key to be in OpenSSH format. Here is an example of a DSA public key in OpenSSH format (usually they are all in one line):

ssh-dss AAAAB3NzaC1kc3MAAACBAJ3hB5SAF6mBXPlZlRoJEZi0KSIN+NU2iGiaXZXi9CDrgVxTp6/
sc56UcYCp4qjfrZ2G3+6PWbxYso4P4YyUC+61RU5KPy4EcTJske3O+aNvec/20cW7PT3TvH1+sxwGry
mD50kTiXDgo5nXdqFvibgM61WW2DGTKlEUsZys0njRAAAAFQDs7ukaTGJlZdeznwFUAttTH9LrwwAAA
IAMm4sLCdvvBx9WPkvWDX0OIXSteCYckiQxesOfPvz26FfYxuTG/2dljDlalC+kYG05C1NEcmZWSNES
GBGfccSYSfI3Y5ahSVUhOC2LMO3JNjVyYUnOM/iyhzrnRfQoWO9GFMaugq0jBMlhZA4UO26yJqJ+BtX
IyItaEEJdc/ghIwAAAIBFeCZynstlbBjP648+mDKIvzNSS+JYr5klGxS3q8A56NPcYhDMxGn7h1DKbb
2AV4pO6y+6hDrWo3UT4dLVuzK01trwp PYp6JXTSZZ12ZaXNPz7sX9/z6pzMqhX4UEfjVsLcuF+ZS6a
QCPO0ZZEa1z+EEIZSD/ykLQsDwPxGjPBqw== someone@somewhere.com

In addition to OpenSSH and Standard SSH formats there are a variety of proprietary formats as well as SSH1 and SSH2 differences to account for, which can make this confusing.

In the example above you will note that the key starts with "ssh-dss". This is because this key was generated using DSA as opposed to RSA. A number of vendors in the SSH arena have argued, as per the PuTTY documentation that can be found at http://the.earth.li/~sgtatham/putty/0.55/htmldoc/Chapter8.html#S8.2.10 that users should employ RSA encryption because

DSA has an intrinsic weakness which makes it very easy to create a signature
which contains enough information to give away the private key! This would
allow an attacker to pretend to be you for any number of future sessions.

An SSH2 public key in OpenSSH format will start with "ssh-rsa".

The idea behind all of this is that once you have keys on the remote server and your local host, access will be simpler since the server will only grant access to someone who has the matching private key.

==Why do I need a SSH key?==

Our CVS server uses OpenSSH, so if you are a Moodle developer and you want to make your logins easier (by avoiding typing in your password all the time) then you will need to submit public key in Openssh format via the "Update my developer information" tab at http://moodle.org/cvs.

==How do I create a SSH key pair?==

===Platform Independent===

Visit http://www.sshkeygen.com and simply follow the directions there.

===Eclipse===

If you plan to use Eclipse for development, please refer to the Eclipse document https://docs.moodle.org/en/Eclipse as Eclipse now has a plugin that allows you to manage all ssh key matters from within Eclipse.

===Unix/Linux===

You can use ssh-keygen at your system prompt. Please consult the man page on your system for the options available to you.

# Run: '''ssh-keygen -t (rsa or dsa)'''. This will not include a passphrase. *
# Use of rsa or dsa above will result in rsa or dsa replacing each XXX below.
# Look in your ~/.ssh directory (or wherever you saved the output). You'll find '''id_XXX''' (private) and '''id_XXX.pub''' (public).
# Cut and paste the contents of '''id_XXX.pub''' into your developer profile on http://moodle.org/cvs
# Put the private key wherever you will be calling CVS from (in your .ssh directory, for example). Make sure it's secure!

* This section initially recommended using ''ssh-keygen -d'' but it is unclear what the source of this -d option might be.

===Windows===
Use puttygen and follow the instructions [http://the.earth.li/~sgtatham/putty/0.58/htmldoc/Chapter8.html here]. Make sure you choose the RSA2 key format and that when you copy the key data into the textbox on the site, that you have all of the characters on one line. If you have opened the key with word pad, it will have line breaks in it which will stop it from working.

The box should look like this:

ssh-rsa
AAAAWfg&jkf4D34H5@4svf..... (single very long line continues beyond edge of textbox)

===Mac OS X===
If you have an existing key in Putty format, open it in puttygen on windows and then choose conversions and export as openssh format. You can then import the key into OS X using
ssh_add -K filename
The -K flag is optional and stores your passphrase in the keychain.

Talk:Gradebook improvements

2010-03-12T21:27:24Z

Mattgibson: /* Common frustrations */ Gradebook lateness

==Aggregation of hidden grades==

Overlook problem partially solve after the database freeze - workaround was to recalculate the grades on the fly so that users that can the hidden grades are ignored. This approach is expensive and can not be used in conditional activities, grade exports, etc.

Solution is to add new flag into grade categories - aggregate hidden grades. Having two values for each grade would be too complex, selective agrragation should solve most of the problems and should be reasonably backwards compatible.

--[[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 11:56, 8 December 2008

==Exports: more flexibility==

Two aspects of the 1.9 export plugin have been criticised by some of Catalyst's clients:

* the fact that grade exports are tied to a course
* the default user profile columns are not all needed and some custom ones would be necessary

Therefore I propose the following changes:

* removing the export plugin dependency on a single course by converting to an array of courses (see MDL-17420)
* making the user-related columns customisable (see MDL-17346)

--[[User:Francois Marier|Francois Marier]] 06:42, 9 December 2008

==Gradebook does not consider groupings functionality==

Student in gradebook view all grade items, but must view only grade items thats belong to his groiping (see MDL-13868).

--[[User:Artem Andreev|Artem Andreev]] 11:07, 9 December 2008

==Common frustrations==
Below are some of the most often reported usability issues in the 1.9 gradebook, which we are trying to address. Several of these are grouped as sub-tasks under MDL-16913.

===Assigning weights to categories and grade items===
This is the most common frustration. Weights are used extensively in many institutions, and were used in 1.8. However, they are difficult to understand in 1.9, and difficult to set up. This issue is discussed extensively in MDL-15680.

===Moving items to categories===
Currently, the [[Edit categories and items]] page lets you move only one grade item or category at a time. It takes two page refreshes and two mouse clicks per move. This is very tedious and time-consuming when many items have to be moved around. MDL-13775 and MDL-12502 address this problem.

===Removing the ''overridden'' attribute of individual grades===
When grades are imported into an existing gradebook, or when grades are manually edited in the grader report, these grades become [[Grade_editing#Overridden|overridden]], which prevents linked activity modules from updating this grade. Removing this attribute is very time-consuming, since one must enter the edit page of each individual grade, untick the checkbox and submit the form. This issue is discussed in [http://moodle.org/mod/forum/discuss.php?d=109636 this forum thread].

===Viewing the overall contribution of each category and item to the course aggregation===
The tracker issue MDL-13777 reports the difficulty in seeing the contribution of each grade item and category to the course total. Calculations and weights may apply, which are not visible in any of the current reports except in each individual category or item's edit page.

--[[User:Nicolas Connault|Nicolas Connault]] 12:41, 4 November 2008

Some more that it would be great to see fixed:
===Setting grade to pass===
Takes a lot of clicks and the edit icon looks like it's part of the main mass of editing icons for the grades table itself, so it's hard to find. This is a very useful feature (at least once MDL-13830 is fixed) as it shows at a glance how many items a student has failed to pass. Seeing a row of red entries is a great way of quickly knowing who to target for extra attention in class. Quite obscure at the moment though, especially seeing as it cannot be done from the module itself. -[[User:Matt Gibson|Matt Gibson]] 07:36, 22 January 2009 (CST)

===Its not possible to see whether or not a student has submitted work which has not been marked===
If the modules could send a special grade e.g. -1 to the gradebook as a placeholder that could be used to add either a css class to a cell, or display a special character to show that work is waiting. Then it would be possible to use the gradebook like a normal one, in order to evaluate students' deadline-meeting for writing reports. At the moment, this is probably the biggest problem in our institution's use of the gradebook. - [[User:Matt Gibson|Matt Gibson]] 07:36, 22 January 2009 (CST)

===Impossible to tell whether work was submitted on time or late===
This is vital for K-12 teachers who are writing reports on students and really needs to be added somehow. Gradebook database changes are needed, so it must be planned as part of a major release. MDL-12111

==Patch for Edit Categories and Items page==
Following is a proposed patch to the '''Edit categories and items''' page in the 1.9 gradebook. It addresses many usability issues while remaining simple. The following features are currently implemented:

===Simple features===
[[Image:gradebook_categories_simple.png|600px]]
*Items and categories are displayed in a table instead of a list. This improves readability and will make drag and drop easier to implement.
*All advanced features are hidden by default, so that the interface by default is almost identical to the original
*An additional column has checkboxes for grade items. All selected items can then be moved to one of the existing grade categories for the current course. Javascript "Select all/Select None" links replace these checkboxes for categories, to make it faster to select or de-select items.

===Advanced features===
[[Image:gradebook_categories_advanced.png|600px]]

*[[Category aggregation|Grade category aggregation type]]: changing this reloads the page, because the grade item weights/extra credits only apply to some of these aggregation types.
*Weight or extra credit: depending on the parent category's aggregation type, each category and grade item may have an input field or a checkbox for weight or extra credit. All these can be edited, then submitted with one click.
*Grade range is displayed for information purposes, but cannot be edited through this interface (it is most often controlled by the linked activity)
*[[Grade_categories#Aggregate_only_non-empty_grades|Aggregate only non-empty grades]]
*[[Grade_categories#Aggregate_including_sub-categories|Aggregate including sub-categories]]
*[[Grade_categories#Include_outcomes_in_aggregation|Include outcomes in aggregation]]
*[[Grade_categories#Drop_the_lowest|Drop the lowest]]
*[[Grade_categories#Keep_the_highest|Keep the highest]]
*[[Grade items|Multiplicator]]
*[[Grade_items|Offset]]

All these settings can be changed then submitted with only one page reload. Just be mindful that changing a category's aggregation type will reload the page and you will lose any non-submitted changes you made to the other settings.

--[[User:Nicolas Connault|Nicolas Connault]] 12:41, 4 November 2008

==Further ideas for 2.0==

The following list is from a gradebook planning meeting on 4 September 2009 between Martin, Nicolas, Petr and Helen:
* Replace hiding as an activity setting with automatic/manual/dated transfer of grades to gradebook
* Duplicate most of the grade item settings into the mod_edit form for each activity (controlled directly by gradebook)
* Implement grading interface centrally for wiki as a test in 2.0, not other modules yet
* Workflow of raw grades in activity -> proposed/hidden grades in gradebook -> final grades released to students
What is the behaviour of hidden grades in calculated grades, exports, teacher view, student view, activity completion ...
* User overviews:
*# Overview of one user (have it now but need to review the capabilities, perhaps one overall is enough but really should check each course
*# Combine multiple gradebooks from one global group into one table of users vs courses, showing final grades for courses
* AJAX-based report to edit rows and columns at once, without reloads
* Adding more switches to turn off things (eg calculations)
* Improving documentation to make it clearer
* Gradebook tracker issues need some rationalisation, update all fix versions (perhaps move all 1.9.6 and 2.0 ones into subtasks like MDL-19131)

--[[User:Helen Foster|Helen Foster]] 11:50, 10 September 2009 (UTC)

==See also==

* [[Tim's_Gradebook_thoughts|Tim's Gradebook thoughts]]

Setting up Netbeans

2010-02-26T14:56:25Z

Mattgibson: Added JIRA module bit

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest [http://netbeans.org/community/releases/68/ 6.8 version] with PHP support, only 25 MB.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

IF you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. <br/>In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)

<p class="note">
Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)
</p>

== Optimization ==

1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within netbeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to Tools->plugins->available plugins and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:NetBeans]]
[[Category:Developer tools|NetBeans]]

AJAX marking block

2010-02-25T14:04:44Z

Mattgibson: /* Constructor */

This page outlines the internal architecture of the AJAX marking block and how to extend it for new types of assignment.

=Architecture=

The block has a server side section of code written in PHP and a client side in javascript. The client is based on the YUI treeview widget and sends asynchronous messages to the server to retrieve the data which becomes the nodes of the tree. Each time a node is clicked to expand it, a new message is sent, with the response data parsed and made into the new sub-nodes.

==HTML fallback==
To aid accessibility, the block starts by loading a very basic HTML version so that if javascript is turned off either in the browser or the user's preferences, the block is still usable. This HTML version is normally not visible as the javascript acts to hide it immediately if possible.

==File structure==
The main lib.php file provides a base class which holds most of the useful functions. This is extended through inheritance when either ajax.php is accessed (each time an asynchronous request is sent) or html_list.php is included when the page is initially set up, providing an object which automatically collects submitted POST data and outputs the desired code once instantiated. This file also has a base class, module_base which is extended by each of the modules with a modulename_functions classin the modulename_grading.php file. All of these files are included as needed at the start and the instantiated objects are added to the main library class object as e.g. $AMB_AJAX_response->quiz so that their functions are available. The module objects will need to use many of the library functions, so a reference to the parent library object is passed in via the constructor and is used as $this->mainobject->useful_function().

The javascript.js file contains a collection of functions which are placed within the YAHOO.ajax_marking_block namespace. Some are part of YAHOO.ajax_marking_block.tree_base which is an extended version of the YAHOO.widget.TreeView widget that gets instantiated once for the main tree and once for the configuration tree via a factory function.

=Plugins=
The block is designed to allow new assessment types to be added dynamically. Rach new type will need to provide two files: modulename_grading.php and modulename_grading.js, whic can be placed either in the /block/ajax_marking folder or in the /mod/modulename folder.

To see how these work, take the assignment_grading files as examples.

==PHP==
The php file will need the following:

The usual login check
require_login(0, false);

A class declaration for modulename_function which extends module_base
class assignment_functions extends module_base {

===Constructor===
A constructor which lays out the basic information about this module
function assignment_functions(&$reference) {

The library object (which this object will be attached to) passed in as a reference so that functions can be accessed
$this->mainobject = $reference;

The type must be identical to the modulename stored in the database
$this->type = 'assignment';

This is the capability that will need to be checked to see if the person has grading permission i.e. teachers should be able to do this whilst students should not.
$this->capability = 'mod/assignment:grade';

This is the location of the icon to be displayed for this assessment type. It varies according to which theme setup you have. Smartpix was difficult to integrate, so there is a home-grown solution using this property, at least for 1.9.
$this->icon = 'mod/assignment/icon.gif';

This array is used to match the types which are returned from the nodes being clicked in the ajax tree to the functions which return the next level of the tree. The initial course->assessment node one is built in, so you just need to add the second and possibly third level connections. In this case, when a node of type 'assignment is clicked, the name of the function that will return the next layer of nodes (the individual student submissions) is 'submissions()'. Groups nodes are dealt with automatically, so there is no need to put them here.
$this->functions = array(
'assignment' => 'submissions'
);

It is possible that your assessment may have only two levels e.g. the journal module. This would be because there is no screen that allows you to grade individual students' work and you must have a pop up for the entire journal with all students. Alternatively, it may be that you can only grade a student's work for a subdivision of an assessment e.g. one question at a time in the quiz. In this case, you will have four levels: course, quiz, quiz question, student. Specify the number of levels here so that the nodes are constructed properly. 3 is the norm.
$this->levels = 3;

==Javascript==
Using the assignment module as an example, the javascript file will need to use the YAHOO.ajax_marking_block.modulename namespace and will have to add the following features:

Make a new namespace for the module:
YAHOO.ajax_marking_block.assignment = {};
The following functions (in no particular order) all use this namespace and must be included even if empty unless otherwise stated.

Provide arguments for the pop up window that the grading will happen in. The main thing to change here is the height and width so that the grading interface is visible.
YAHOO.ajax_marking_block.assignment.pop_up_arguments = function(clicked_node) {
return 'menubar=0,location=0,scrollbars,resizable,width=780,height=630';
};

Provide the URL for the pop up window. This will usually involve some combination of the student's userid and the assessement id or coursemodule id. This data is saved in the data attribute of the clicked node and is passed through to this function. You will need to make sure it is passed through by the PHP code on the server.
YAHOO.ajax_marking_block.assignment.pop_up_opening_url = function (clicked_node) {
return '/mod/assignment/submissions.php?id='+clicked_node.data.aid+'&userid='+clicked_node.data.sid+'&mode=single&offset=0';
};

The pop up window needs to be closed after grading has finished, which a small piece of javascript carries out. It does this by checking to see if the URL has changed to the one signifying that your grades have been saved, so grade some work, press 'save' and look to see the URL, which you put in this function.
YAHOO.ajax_marking_block.assignment.pop_up_closing_url = function (clicked_node) {
return '/mod/assignment/submissions.php';
};

There may be a need to send more than just the standard user id and assessment item id with the AJAX request in order to specify what's needed. See the quiz module for an example, where the quiz id and question id are needed as well as the user id. Leave it as below if not required.

YAHOO.ajax_marking_block.assignment.extra_ajax_request_arguments = function (clicked_node) {
return true;
};

You then need to provide code that will alter the pop up's contents so that when the submit button is clicked, the tree nodes are updated. The function below will be run every second from the point at which the pop up is opened until it completes successfully. It aims to test the loaded portion of the DOM to see whether the buttons that need altering are present, then adds an onclick function which will update the tree.

YAHOO.ajax_marking_block.assignment.alter_popup = function(node_id) {

var els = '';

if (YAHOO.ajax_marking_block.pop_up_holder.document.getElementsByName) {

els = YAHOO.ajax_marking_block.pop_up_holder.document.getElementsByName('submit');
// the above line will not return anything until the pop up is fully loaded

if (els.length > 0) {
var functionText = "return YAHOO.ajax_marking_block.main_instance.remove_node_from_tree(-1, '";
functionText += node_id+"', false); ";

els[0]["onclick"] = new Function(functionText);

// cancel the timer loop for this function
window.clearInterval(YAHOO.ajax_marking_block.timerVar);
}
}
}

AJAX marking block

2010-02-25T14:04:27Z

Mattgibson: /* Constructor */

AJAX marking block

2010-02-25T13:55:41Z

Mattgibson: /* Javascript */

AJAX marking block

2010-02-25T13:40:58Z

Mattgibson: /* PHP */

AJAX marking block

2010-02-25T13:00:18Z

Mattgibson:

This page outlines the internal architecture of the AJAX marking block and how to extend it for new types of assignment.

=Architecture=

The block has a server side section of code written in PHP and a client side in javascript. The client is based on the YUI treeview widget and sends asynchronous messages to the server to retrieve the data which becomes the nodes of the tree. Each time a node is clicked to expand it, a new message is sent, with the response data parsed and made into the new sub-nodes.

==HTML fallback==
To aid accessibility, the block starts by loading a very basic HTML version so that if javascript is turned off either in the browser or the user's preferences, the block is still usable. This HTML version is normally not visible as the javascript acts to hide it immediately if possible.

==File structure==
The main lib.php file provides a base class which holds most of the useful functions. This is extended through inheritance when either ajax.php is accessed (each time an asynchronous request is sent) or html_list.php is included when the page is initially set up, providing an object which automatically collects submitted POST data and outputs the desired code once instantiated. This file also has a base class, module_base which is extended by each of the modules with a modulename_functions classin the modulename_grading.php file. All of these files are included as needed at the start and the instantiated objects are added to the main library class object as e.g. $AMB_AJAX_response->quiz so that their functions are available. The module objects will need to use many of the library functions, so a reference to the parent library object is passed in via the constructor and is used as $this->mainobject->useful_function().

The javascript.js file contains a collection of functions which are placed within the YAHOO.ajax_marking_block namespace. Some are part of YAHOO.ajax_marking_block.tree_base which is an extended version of the YAHOO.widget.TreeView widget that gets instantiated once for the main tree and once for the configuration tree via a factory function.

=Plugins=
The block is designed to allow new assessment types to be added dynamically. Rach new type will need to provide two files: modulename_grading.php and modulename_grading.js, whic can be placed either in the /block/ajax_marking folder or in the /mod/modulename folder.

To see how these work, take the assignment_grading files as examples.

==PHP==
The php file will need the following functions as a minimum:

==Javascript==
Using the assignment module as an example, the javascript file will need to use the YAHOO.ajax_marking_block.modulename namespace and will have to add the following features:

Make a new namespace for the module:
YAHOO.ajax_marking_block.assignment = {};
The following functions (in no particular order) all use this namespace and must be included even if empty unless otherwise stated.

Provide arguments for the pop up window that the grading will happen in. The main thing to change here is the height and width so that the grading interface is visible.
YAHOO.ajax_marking_block.assignment.pop_up_arguments = function(clicked_node) {
return 'menubar=0,location=0,scrollbars,resizable,width=780,height=630';
};

Provide the URL for the pop up window. This will usually involve some combination of the student's userid and the assessement id or coursemodule id. This data is saved in the data attribute of the clicked node and is passed through to this function. You will need to make sure it is passed through by the PHP code on the server.
YAHOO.ajax_marking_block.assignment.pop_up_opening_url = function (clicked_node) {
return '/mod/assignment/submissions.php?id='+clicked_node.data.aid+'&userid='+clicked_node.data.sid+'&mode=single&offset=0';
};

The pop up window needs to be closed after grading has finished, which a small piece of javascript carries out. It does this by checking to see if the URL has changed to the one signifying that your grades have been saved, so grade some work, press 'save' and look to see the URL, which you put in this function.
YAHOO.ajax_marking_block.assignment.pop_up_closing_url = function (clicked_node) {
return '/mod/assignment/submissions.php';
};

There may be a need to send more than just the standard user id and assessment item id with the AJAX request in order to specify what's needed. See the quiz module for an example, where the quiz id and question id are needed as well as the user id. Leave it as below if not required.

YAHOO.ajax_marking_block.assignment.extra_ajax_request_arguments = function (clicked_node) {
return true;
};

You then need to provide code that will alter the pop up's contents so that when the submit button is clicked, the tree nodes are updated. The function below will be run every second from the point at which the pop up is opened until it completes successfully. It aims to test the loaded portion of the DOM to see whether the buttons that need altering are present, then adds an onclick function which will update the tree.

YAHOO.ajax_marking_block.assignment.alter_popup = function(node_id) {

var els = '';

if (YAHOO.ajax_marking_block.pop_up_holder.document.getElementsByName) {

els = YAHOO.ajax_marking_block.pop_up_holder.document.getElementsByName('submit');
// the above line will not return anything until the pop up is fully loaded

if (els.length > 0) {
var functionText = "return YAHOO.ajax_marking_block.main_instance.remove_node_from_tree(-1, '";
functionText += node_id+"', false); ";

els[0]["onclick"] = new Function(functionText);

// cancel the timer loop for this function
window.clearInterval(YAHOO.ajax_marking_block.timerVar);
}
}
}

AJAX marking block

2010-02-25T09:14:36Z

Mattgibson:

AJAX marking block

2010-02-25T00:24:15Z

Mattgibson: Began page

Setting up Netbeans

2010-01-19T09:36:42Z

Mattgibson: added memory optimisation link

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* I recommend downloading the latest [http://www.netbeans.org/downloads/indexB.html 6.7.1 version with PHP support ]. It's only a 26 MB download.
* Install and run it.

* There's also the brand new [http://netbeans.org/community/releases/68/ NetBeans 6.8 Beta release].

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

IF you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. <br/>In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Optimization ==

1. You may want to run Netbeans with the Sun JDK. Netbeans seems to work a bit better with the Sun JDK. Download it from [http://java.sun.com/javase/downloads/index.jsp]. You'll have to edit Netbeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the Netbeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If Netbeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See [http://wiki.netbeans.org/FaqSettingHeapSize here] for more details on memory optimisation.

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

== See also: ==
* Moodle forum: [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

[[Category:NetBeans]]
[[Category:Developer tools|NetBeans]]

Setting up Netbeans

2009-11-19T14:31:02Z

Mattgibson: Adding a branch to your plugin

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* I recommend downloading the latest [http://www.netbeans.org/downloads/indexB.html 6.7.1 version with PHP support ]. It's only a 26 MB download.
* Install and run it.

* There's also the brand new [http://netbeans.org/community/releases/68/ NetBeans 6.8 Beta release].

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

IF you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. <br/>In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Optimization ==

1. You may want to run Netbeans with the Sun JDK. Netbeans seems to work a bit better with the Sun JDK. Download it from [http://java.sun.com/javase/downloads/index.jsp]. You'll have to edit Netbeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the Netbeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If Netbeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

== See also: ==
* Moodle forum: [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

[[Category:NetBeans]]
[[Category:Developer tools|NetBeans]]

Setting up Netbeans

2009-11-10T23:41:19Z

Mattgibson: /* CVS with NetBeans */ Added instructions for developers with write access

Setting up Netbeans

2009-11-06T12:48:03Z

Mattgibson: small typo

Talk:Community hub

2009-07-06T11:37:01Z

Mattgibson:

Regarding the course import for teachers to start from...
I can envisage a situation whereby the original course author finds new information/ideas and adds stuff to the master course after the teacher has downloaded it, which in the current model would not make it to the teacher as the download is a one off process which they will not repeat. I would prefer a model whereby a course can act as a master template which gets updated regularly so that new questions, resources, activities etc appear dynamically as hidden items within the teacher's downloaded course, ready to be reviewed and revealed if needed. This would be like maintaining your Moodle install using CVS - you get updates all the time as they are created.

It would also be good to be able to track how many people are using a particular course and to have some sort of meta-forum for discussing changes and developemts. Many teachers will end up using the successful/well designed courses, so it would make a lot of sense to have a way of pooling their shared experience and getting that feedback back to the original creator. -- [[User:Matt Gibson|Matt Gibson]] 18:51, 25 June 2009 (UTC)

== Harvesting courses regularly and a few other comments ==

I've put this in the forum, but I'll say it here as well. If a site has a lot of courses to share with a hub, perhaps because they are an OpenCourseWare provider, they might prefer to supply an RSS or OAI list rather than click "publish" on each individual course. OCW Consortium members are already encouraged to offer an RSS feed (with DC metadata) of all their courses that is picked up by a number of OCW search tools. I'm sure Moodle users in that community would love the same approach to mean they could be included in the hubs as well.

To aid course harvesting (but to make publishing easier anyway) I'd like to see the DC metadata editing screen become part of the standard course settings screen, and the data pulled from here as part of the publish to hub functionality (and into any RSS or OAI service).

Using LOM as well as (or instead of) DC would allow more flexible searching at the hub with relatively little extra cost of data inputting.

Finally, there is a great deal of discussion in the OCW community about asset-level re-use. Anecdotal evidence from teachers suggests that the course-level is not fine-grained enough and they'd prefer to pick a single resource/image/activity. See http://opencontent.org/blog/archives/900 and related comments for example. So I'd like to see DC metadata added to resources and modules too, and the searching and import/export/enrol facility in the hub system work at this level also.
-- [[User:Jenny Gray|Jenny Gray]] 14:48, 30 June 2009 (GMT)

I second the points Jenny made above. I can't see much call for importing a whole course, as it will be too much hassle to integrate with current stuff. Ideally, single activities and resources can be copied at once from a remote course. This is already possible within a single site using the contributed sharing cart block, and if this could be brought into core and made to work across sites, it would be a killer app.

If that gets done, it brings up an issue of copyright - some courses will have things that are only licenced for site use and cannot be shared. If there was a switch that would set the item to 'can't copy/view over mnet', then it would be possible to allow access to courses with commercial resources and only share the parts which a teacher has made themselves.

For me, this use case would be an absolute killer app and would make collaboration a breeze across whole countries at a time. -- [[User:Matt Gibson|Matt Gibson]] 11:37, 6 July 2009 (UTC)

Talk:Community hub

2009-06-25T18:55:09Z

Mattgibson:

Talk:Community hub

2009-06-25T18:54:54Z

Mattgibson:

Talk:Community hub

2009-06-25T18:51:26Z

Mattgibson:

Old Events API

2009-05-26T11:27:26Z

Mattgibson:

{{Moodle 1.9}}

==Overview==

The Events API is a core system in Moodle to allow communication between modules.

An '''event''' is when something "interesting" happens in Moodle that is worth alerting the system about.

Any Moodle modules can '''trigger''' new events (with attached data), and other modules can elect to '''handle''' those events with custom functions that operate on the given data.

==Example==

Let's look at an example of how events are used to implement Messaging in Moodle 2.0. In the messaging system, textual messages are generated for users by different modules, and the user can decide how certain types of messages are displayed.

===Triggering an event===

When a messaging event occurs, the module should trigger a "message_send" event. In this example let's pretend someone just posted to a forum.

The forum module needs to create an object with the data that this event needs. This may vary completely for different types of events, it's just a data object.

$eventdata = new object();
$eventdata->component = 'mod/forum'; // path in Moodle
$eventdata->name = 'posts'; // type of message from that module (as module defines it)
$eventdata->userfrom = $userfrom; // user object
$eventdata->userto = $userto; // user object
$eventdata->subject = "Hi there"; // short one-line subject
$eventdata->fullmessage = "Here is the full message"; // raw text
$eventdata->fullmessageformat = FORMAT_PLAIN; // text format
$eventdata->fullmessagehtml = "Here is the <b>full</b> message"; // html rendered version (optional)
$eventdata->smallmessage = "Here is the truncated message"; // useful for plugins like sms or twitter (optional)

Then we post the object as an event and forget about it:

events_trigger('message_send', $eventdata);

===Handling an event===

Modules or core code can define an events.php in the db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For this case, there is this definition of a handler in lib/db/events.php

$handlers = array (
'message_send' => array (
'handlerfile' => '/lib/messagelib.php',
'handlerfunction' => 'message_send_handler',
'schedule' => 'instant'
)
);

These events.php files are parsed during install / upgrade and stored in a simple database table.

Now, when a '''message_send''' event happens, all the registered handlers functions for that event will be called something like this (but with more error handling):

include_once($CFG->dirroot.$handlers['message_send']['handlerfile']);
call_user_func($handlers['message_send']['handlerfunction'], $eventdata);

Any code can hook into any events this way.

==Database structure==

There are 3 core tables for events. Note that if a handler is queued, and yet to be processed or processing failed, then all subsequent calls on that handler must be queued.

===events_handlers===

This table is for storing which components requests what type of event, and the location of the responsible handler functions.

These entries are created by parsing events.php files in all the modules, and can be rebuilt any time (during an upgrade, say).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventname
|varchar(255)
|name of the event, e.g. 'message_send'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /lib/messagelib.php
|-
|handlerfunction
|text
|serialized string or array describing function, suitable to be passed to '''call_user_func()'''
|-
|schedule
|varchar(255)
|'cron' or 'instant'.
|-
|status
|int(10)
|number of failed attempts to process this handler
|}

===events_queue===

This table is for storing queued events. It stores only one copy of the eventdata here, and entries from this table are being references by the events_queue_handlers table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventdata
|longtext
|serialized version of the data object passed to the event handler.
|-
|stackdump
|text
|serialized debug_backtrace showing where the event was fired from
|-
|userid
|int(10)
|$USER->id when the event was fired
|-
|timecreated
|int(10)
|time stamp of the first time this was added
|}

===events_queue_handlers===

This is the list of queued handlers for processing. The event object is retrieved from the events_queue table. When no further reference is made to the events_queue table, the corresponding entry in the events_queue table should be deleted. Entry should get deleted (?) after a successful event processing by the specified handler. The status field keeps track of failures, after it gets to a certain number (eg 10?) it should trigger an "event failed" event (that could result in admin being emailed etc, or perhaps even the originating module taking care of it or rolling something back etc).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|queuedeventid
|int(10)
|foreign key id corresponding to the id of the event_queues table
|-
|handlerid
|int(10)
|foreign key id corresponding to the id of the event_handlers table
|-
|status
|int(10)
|number of failed attempts to process this handler
|-
|errormessage
|text
|if an error happened last time we tried to process this event, record it here.
|-
|timemodified
|int(10)
|time stamp of the last attempt to run this from the queue
|}

==Standards for naming events==

All event names should follow a consistent naming pattern, such as modulename_noun_verb

==Events which exist==

When we add new events to core we should always add them here too.

Under each event, list the data sent as part of the event.

===Users===
* user_created
** full new record from 'user' table
* user_updated
** full new record from 'user' table

===Courses===
* course_created
** full course record
* course_updated
** full course record
* course_deleted
** full course record
* course_category_deleted
** full category record

===Groups===
* groups_member_added
** groupid
** userid
* groups_member_removed
** groupid
** userid
* groups_group_created
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_updated
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_deleted
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_grouping_created
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_updated
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_deleted
** id
** courseid
** name
** timecreated
** timemodified
* groups_members_removed (user deleted from all groups in a course)
** courseid
** userid
* groups_groupings_groups_removed (remove all groups from all groupings in a course)
** courseid (as plain integer, not object)
* groups_groups_deleted (delete all groups in a course)
** courseid (as plain integer, not object)
* groups_groupings_deleted (delete all groupings in a course)
** courseid (as plain integer, not object)

===Messaging===
* message_send
** component = 'mod/forum': path in Moodle
** name = 'posts': type of message from that module (as module defines it)
** userfrom = $userfrom: a user object to send from
** userto = $userto: a user object to send to
** subject = 'subject line': a short text line
** fullmessage = 'full plain text': raw text as entered by user
** fullmessageformat = FORMAT_PLAIN|FORMAT_HTML|FORMAT_MOODLE|FORMAT_MARKDOWN: the format of this text
** fullmessagehtml = 'long html text'; html rendered version (optional)
** smallmessage = 'short text': useful for plugins like sms or twitter (optional)

===Portfolio===
* portfolio_send
** id : recordid in portfolio_tempdata table, used for itemid in file storage

==Events wishlist==

List of events which it would be nice to have. Please add to this list if what you want is not shown here.

* user_assign_role
* user_unassign_role
* mform_print_form -- this for all types of form e.g. admin settings, user profile, module updating, + some sort of standard way of discriminiating between them e.g. if ($form->name == 'user_profile') {}. This would be better triggered at the end of the form generation process so that new bits can be inserted at any point, or existing bits could be removed.

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[Messaging_2.0]]

[[Category:Events]]
[[Category:Grades]]

Resource module file API migration

2009-05-18T08:53:16Z

Mattgibson: /* Current problems */

{{Moodle_2.0}}

=Current problems=
* text and html resource types separate
* embedded images and files in general are stored in course files without appropriate access control
* local files and Internet links mixed
* is IMS plug-in maintained?
* repository plug-in obsoleted
* embedded images are lost during backup & restore which moves the course to a new site. -- [[User:Matt Gibson|Matt Gibson]] 08:53, 18 May 2009 (UTC)

=Types of resources=
* Directory of files
* Resource page - using new editor element
* External resource link - some file stored elsewhere
* Single uploaded images and files
* Packages and uploaded html files
* Other 3rd party plugins

=Upgrade planning=
Each type requires different upgrade code.

==Directory type==
# Recursively copy directory to resource area, skip backup and moddata contents

==Text and web page==
# Convert to one plug-in using new editor forms element
# Copy directly linked files that may not contain other relative links to resource area
# PROBLEM: deal somehow with html, flash, and java; maybe just warn and manual migration button

==Links to files==
# Links to external sites do not need any upgrade
# If link points to simple file (image, sound, pdf.) copy to resource area
# PROBLEM: links to different courses - already problem now, maybe just warn teachers
# PROBLEM: links to files that may contain other relative links (html, flash, java)

==IMS type==
# copy files to resource area

==hive==
# PROBLEM: remove from core completely?

==3rd party==
# needs docs

=Solution of caching problems=
Teachers often do not understand that files may be cached in browsers, se the same mechanism already implemented in SCORM module.
# Internally store all files as itemid=0
# Add new revision db field into resource table
# When serving files always construct links with itemid==revision
# Ignore itemid for resource files in pluginfile.php

=Internal refactoring and UI changes=
...

=See also=

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

YUI

2009-05-13T15:27:30Z

Mattgibson:

The Yahoo! User Interface (YUI) Library is a set of utilities and controls, written in JavaScript, for building richly interactive web applications using techniques such as DOM scripting, DHTML and AJAX. All components in the YUI Library have been released as open source under a BSD license and are free for all uses. Details of the YUI can be found at the [http://developer.yahoo.com/yui/index.html Yahoo Developer Website].

==Getting started==

Broadly speaking, you find an example you'd like to implement e.g. from [http://developer.yahoo.com/yui/examples/slider/index.html here], then add it to an existing page, then tweak it to do what you want.

YUI works with a single global object called YAHOO, which all other functions are added to via namespacing. You then use them like this:
YAHOO.util.Event.onDOMready(//do something );

===Dependencies===
In order to make the onDOMready method available to you, you first include a .js file that sets up the global object, then the events library .js file that adds all of the events methods to it. Moodle's way of doing this is with the require_js() function:
<?php require_js(array('yui_yahoo', 'yui_event')); ?>
You can see that you can use shortcuts for many of the libraries. the ajax_get_lib() function in /lib/ajax/ajaxlib.php has details. Otherwise, you use the full path like this:
<?php require_js(array($CFG->dirroot.'/lib/yui/yahoo/yahoo-min.js', $CFG->dirroot.'/lib/yui/event/event-min.js')); ?>
You notice that the files are called xxx-min.js. This is because they have been minified to make them as small as possible for fast page loading. Every file comes in a non-minifed version too called xxx-debug.js, which will give you accurate error messages as well as letting you follow progress in the YUI logger console.

Once you have included the various .js dependency files with require_js() as outlined above, then write your own source .js file and add that to the require_js array '''after''' the other YUI ones. Many of the YUI files have other dependencies, so you'll often need to include more than one and the order matters for them too. Just follow the examples.

You can also inject libraries dynamically if you really want to using [http://developer.yahoo.com/yui/yuiloader/ YUI loader], which adds <script> and <link> tags on the fly and can keep initial page load lighter.

===Skinning===
For CSS, you include the css dependency files in either your theme styles.php or module/block styles.php using the standard PHP include() function. You will often need to apply the yui-skin-sam style to the body tag to get the skins to work right, so add something near the top of your script like:
document.body.className += ' yui-skin-sam';
As a caveat, the paths in the CSS files assume that yui is placed in the site's web root and have no reference to $CFG->wwwroot, so none of the images work. The solution is to go through the CSS files, pulling out any that have
background: url(../../whatever.png);
and paste them into your styles.php below the css include you've added, but looking like this:
background: url(<?php echo $CFG->wwwroot ?>/lib/yui/whatever.png);

==Performance==
Remember to use [http://developer.yahoo.com/yui/examples/event/event-delegation.html event bubbling] wherever possible so that instead of adding a drag-drop listener to every page element, you just add one to the content div which catches all of the events lower down the DOM tree and does what's needed.

==Debugging==
Ideally, you should use Firefox, with the [https://addons.mozilla.org/en-US/firefox/addon/60 webdeveloper], [https://addons.mozilla.org/en-US/firefox/addon/1843 Firebug] and [https://addons.mozilla.org/en-US/firefox/addon/5369 YSlow] extensions loaded. The YUI logger will need to be included as a dependency if you want to use the xxx-debug.js versions of the files, so you need to add it to require_js() before them.

==Documentation for specific libraries==

*[[Yahoo Global Object]] (/lib/yui/yahoo/yahoo.js)
*[[YUI event utility|YUI event utility]] (/lib/yui/event/event.js)
*[[Yahoo DOM Manipulation ]] (/lib/yui/dom/dom.js)
*[[Yahoo Connection Manager]] (/lib/yui/connection/connection.js)
*[[Yahoo Drag and Drop Utility]] (/lib/yui/dragdrop/dragdrop.js)
*[[Yahoo Animation Utility]] (/lib/yui/animation/animation.js)
*[[YUI TreeView|YUI TreeView]] (/lib/yui/treeview/treeview.js)
*[[Yahoo logger]] (/lib/yui/logger/logger-min.js)

[[Category:Javascript|YUI]]
[[Category:AJAX|YUI]]

{{CategoryDeveloper}}

YUI

2009-05-13T15:27:01Z

Mattgibson:

The Yahoo! User Interface (YUI) Library is a set of utilities and controls, written in JavaScript, for building richly interactive web applications using techniques such as DOM scripting, DHTML and AJAX. All components in the YUI Library have been released as open source under a BSD license and are free for all uses. Details of the YUI can be found at the [http://developer.yahoo.com/yui/index.html Yahoo Developer Website].

==Getting started==

Broadly speaking, you find an example you'd like to implement e.g. from [http://developer.yahoo.com/yui/examples/slider/index.html here], then add it to an existing page, then tweak it to do what you want.

YUI works with a single global object called YAHOO, which all other functions are added to via namespacing. You then use them like this:
YAHOO.util.Event.onDOMready(//do something );

===Dependencies===
In order to make the onDOMready method available to you, you first include a .j file that sets up the global object, then the events library .js file that adds all of the events methods to it. Moodle's way of doing this is with the require_js() function:
<?php require_js(array('yui_yahoo', 'yui_event')); ?>
You can see that you can use shortcuts for many of the libraries. the ajax_get_lib() function in /lib/ajax/ajaxlib.php has details. Otherwise, you use the full path like this:
<?php require_js(array($CFG->dirroot.'/lib/yui/yahoo/yahoo-min.js', $CFG->dirroot.'/lib/yui/event/event-min.js')); ?>
You notice that the files are called xxx-min.js. This is because they have been minified to make them as small as possible for fast page loading. Every file comes in a non-minifed version too called xxx-debug.js, which will give you accurate error messages as well as letting you follow progress in the YUI logger console.

Once you have included the various .js dependency files with require_js() as outlined above, then write your own source .js file and add that to the require_js array '''after''' the other YUI ones. Many of the YUI files have other dependencies, so you'll often need to include more than one and the order matters for them too. Just follow the examples.

You can also inject libraries dynamically if you really want to using [http://developer.yahoo.com/yui/yuiloader/ YUI loader], which adds <script> and <link> tags on the fly and can keep initial page load lighter.

===Skinning===
For CSS, you include the css dependency files in either your theme styles.php or module/block styles.php using the standard PHP include() function. You will often need to apply the yui-skin-sam style to the body tag to get the skins to work right, so add something near the top of your script like:
document.body.className += ' yui-skin-sam';
As a caveat, the paths in the CSS files assume that yui is placed in the site's web root and have no reference to $CFG->wwwroot, so none of the images work. The solution is to go through the CSS files, pulling out any that have
background: url(../../whatever.png);
and paste them into your styles.php below the css include you've added, but looking like this:
background: url(<?php echo $CFG->wwwroot ?>/lib/yui/whatever.png);

==Performance==
Remember to use [http://developer.yahoo.com/yui/examples/event/event-delegation.html event bubbling] wherever possible so that instead of adding a drag-drop listener to every page element, you just add one to the content div which catches all of the events lower down the DOM tree and does what's needed.

==Debugging==
Ideally, you should use Firefox, with the [https://addons.mozilla.org/en-US/firefox/addon/60 webdeveloper], [https://addons.mozilla.org/en-US/firefox/addon/1843 Firebug] and [https://addons.mozilla.org/en-US/firefox/addon/5369 YSlow] extensions loaded. The YUI logger will need to be included as a dependency if you want to use the xxx-debug.js versions of the files, so you need to add it to require_js() before them.

==Documentation for specific libraries==

*[[Yahoo Global Object]] (/lib/yui/yahoo/yahoo.js)
*[[YUI event utility|YUI event utility]] (/lib/yui/event/event.js)
*[[Yahoo DOM Manipulation ]] (/lib/yui/dom/dom.js)
*[[Yahoo Connection Manager]] (/lib/yui/connection/connection.js)
*[[Yahoo Drag and Drop Utility]] (/lib/yui/dragdrop/dragdrop.js)
*[[Yahoo Animation Utility]] (/lib/yui/animation/animation.js)
*[[YUI TreeView|YUI TreeView]] (/lib/yui/treeview/treeview.js)
*[[Yahoo logger]] (/lib/yui/logger/logger-min.js)

[[Category:Javascript|YUI]]
[[Category:AJAX|YUI]]

{{CategoryDeveloper}}

SSH key

2009-03-26T12:57:50Z

Mattgibson: /* Windows */

==What is a SSH key?==

SSH keys are used for secure connections across a network. They come in pairs, so you have a public key and a private key.

The standard ssh2 file format (see
http://www.openssh.org/txt/draft-ietf-secsh-publickeyfile-02.txt)
looks like this:

---- BEGIN SSH2 PUBLIC KEY ----
Comment: "jtbell@Jon-Bells-Computer"
AAAAB3NzaC1kc3MAAACBAPNgmidbM2rhYjUXunpnlXjHWfV+vc8/5YKrn8Y5P0Y6KwmG2G
GMgNBon3LX3iJlBhtuU3FCBj3G1Kdt5vUhQHhUmHVrOasi47vawTrv7ZJCfiaSGwRsiBHt
Jta5CAp7t0EnzX2q6BvPbFBBHNLyy6uNVpL2jOR06Pkx/vaqyScvAAAAFQDHvwmjWYwK9g
K6Sp+pSvI7bwEUtwAAAIANMJDotMpfj89N+7+FJylSS+uFEQSS61PxENl/Mcj1jUREjJg2
eNsJdAB9Ev99hWYS+7lFRtTJ2eh4Y9gpGe7BX3e2YGHOqp8cWCVCIKaMzwk9To+xnfThWq
IfHT8I6CJxp/5ez02m6F2k/5iukvOwbGms6EAZK1DTBhDOHjEQwQAAAIAlz2/qBWkaMP+s
W8FLmGKM+cCw5+asOaJGTwrFVuwJkDMvdEWxmG92A2dxuUske0d/AkN6zJp7HD0wlfesRM
3+c+Res5qun9lFcdM4i03VoV5mXd+T7laS8yku6vZgvZZFnPvr2LOUnc7XThGFwMaQpFEW
U8cvQbttO6QrT2CD2w==
---- END SSH2 PUBLIC KEY ----

However, Moodle uses OpenSSH on its server and this key will not work with the OpenSSH server in this format; OpenSSH requires the key to be in OpenSSH format. Here is an example of a DSA public key in OpenSSH format (usually they are all in one line):

ssh-dss AAAAB3NzaC1kc3MAAACBAJ3hB5SAF6mBXPlZlRoJEZi0KSIN+NU2iGiaXZXi9CDrgVxTp6/
sc56UcYCp4qjfrZ2G3+6PWbxYso4P4YyUC+61RU5KPy4EcTJske3O+aNvec/20cW7PT3TvH1+sxwGry
mD50kTiXDgo5nXdqFvibgM61WW2DGTKlEUsZys0njRAAAAFQDs7ukaTGJlZdeznwFUAttTH9LrwwAAA
IAMm4sLCdvvBx9WPkvWDX0OIXSteCYckiQxesOfPvz26FfYxuTG/2dljDlalC+kYG05C1NEcmZWSNES
GBGfccSYSfI3Y5ahSVUhOC2LMO3JNjVyYUnOM/iyhzrnRfQoWO9GFMaugq0jBMlhZA4UO26yJqJ+BtX
IyItaEEJdc/ghIwAAAIBFeCZynstlbBjP648+mDKIvzNSS+JYr5klGxS3q8A56NPcYhDMxGn7h1DKbb
2AV4pO6y+6hDrWo3UT4dLVuzK01trwp PYp6JXTSZZ12ZaXNPz7sX9/z6pzMqhX4UEfjVsLcuF+ZS6a
QCPO0ZZEa1z+EEIZSD/ykLQsDwPxGjPBqw== someone@somewhere.com

In addition to OpenSSH and Standard SSH formats there are a variety of proprietary formats as well as SSH1 and SSH2 differences to account for, which can make this confusing.

In the example above you will note that the key starts with "ssh-dss". This is because this key was generated using DSA as opposed to RSA. A number of vendors in the SSH arena have argued, as per the PuTTY documentation that can be found at http://the.earth.li/~sgtatham/putty/0.55/htmldoc/Chapter8.html#S8.2.10 that users should employ RSA encryption because

DSA has an intrinsic weakness which makes it very easy to create a signature
which contains enough information to give away the private key! This would
allow an attacker to pretend to be you for any number of future sessions.

An SSH2 public key in OpenSSH format will start with "ssh-rsa".

The idea behind all of this is that once you have keys on the remote server and your local host, access will be simpler since the server will only grant access to someone who has the matching private key.

==Why do I need a SSH key?==

Our CVS server uses OpenSSH, so if are a Moodle developer and you want to make your logins easier (by avoiding typing in your password all the time) then you will need to submit public key in Openssh format via the "Update my developer information" tab at http://moodle.org/cvs.

==How do I create a SSH key pair?==

===Platform Independent===

Visit http://www.sshkeygen.com and simply follow the directions there.

===Eclipse===

If you plan to use Eclipse for development, please refer to the Eclipse document https://docs.moodle.org/en/Eclipse as Eclipse now has a plugin that allows you to manage all ssh key matters from within Eclipse.

===Unix/Linux===

You can use ssh-keygen at your system prompt. Please consult the man page on your system for the options available to you.

# Run: '''ssh-keygen -t (rsa or dsa)'''. This will not include a passphrase. *
# Use of rsa or dsa above will result in rsa or dsa replacing each XXX below.
# Look in your ~/.ssh directory (or wherever you saved the output). You'll find '''id_XXX''' (private) and '''id_XXX.pub''' (public).
# Cut and paste the contents of '''id_XXX.pub''' into your developer profile on http://moodle.org/cvs
# Put the private key wherever you will be calling CVS from (in your .ssh directory, for example). Make sure it's secure!

* This section initially recommended using ''ssh-keygen -d'' but it is unclear what the source of this -d option might be.

===Windows===
Use puttygen and follow the instructions [http://the.earth.li/~sgtatham/putty/0.58/htmldoc/Chapter8.html here]. Make sure you choose the RSA2 key format and that when you copy the key data into the textbox on the site, that you have all of the characters on one line. If you have opened the key with word pad, it will have line breaks in it which will stop it from working.

The box should look like this:

ssh-rsa
AAAAWfg&jkf4D34H5@4svf..... (single very long line continues beyond edge of textbox)

===Mac OS X===

SSH key

2009-03-26T12:54:44Z

Mattgibson: /* Windows */

==What is a SSH key?==

SSH keys are used for secure connections across a network. They come in pairs, so you have a public key and a private key.

The standard ssh2 file format (see
http://www.openssh.org/txt/draft-ietf-secsh-publickeyfile-02.txt)
looks like this:

---- BEGIN SSH2 PUBLIC KEY ----
Comment: "jtbell@Jon-Bells-Computer"
AAAAB3NzaC1kc3MAAACBAPNgmidbM2rhYjUXunpnlXjHWfV+vc8/5YKrn8Y5P0Y6KwmG2G
GMgNBon3LX3iJlBhtuU3FCBj3G1Kdt5vUhQHhUmHVrOasi47vawTrv7ZJCfiaSGwRsiBHt
Jta5CAp7t0EnzX2q6BvPbFBBHNLyy6uNVpL2jOR06Pkx/vaqyScvAAAAFQDHvwmjWYwK9g
K6Sp+pSvI7bwEUtwAAAIANMJDotMpfj89N+7+FJylSS+uFEQSS61PxENl/Mcj1jUREjJg2
eNsJdAB9Ev99hWYS+7lFRtTJ2eh4Y9gpGe7BX3e2YGHOqp8cWCVCIKaMzwk9To+xnfThWq
IfHT8I6CJxp/5ez02m6F2k/5iukvOwbGms6EAZK1DTBhDOHjEQwQAAAIAlz2/qBWkaMP+s
W8FLmGKM+cCw5+asOaJGTwrFVuwJkDMvdEWxmG92A2dxuUske0d/AkN6zJp7HD0wlfesRM
3+c+Res5qun9lFcdM4i03VoV5mXd+T7laS8yku6vZgvZZFnPvr2LOUnc7XThGFwMaQpFEW
U8cvQbttO6QrT2CD2w==
---- END SSH2 PUBLIC KEY ----

However, Moodle uses OpenSSH on its server and this key will not work with the OpenSSH server in this format; OpenSSH requires the key to be in OpenSSH format. Here is an example of a DSA public key in OpenSSH format (usually they are all in one line):

ssh-dss AAAAB3NzaC1kc3MAAACBAJ3hB5SAF6mBXPlZlRoJEZi0KSIN+NU2iGiaXZXi9CDrgVxTp6/
sc56UcYCp4qjfrZ2G3+6PWbxYso4P4YyUC+61RU5KPy4EcTJske3O+aNvec/20cW7PT3TvH1+sxwGry
mD50kTiXDgo5nXdqFvibgM61WW2DGTKlEUsZys0njRAAAAFQDs7ukaTGJlZdeznwFUAttTH9LrwwAAA
IAMm4sLCdvvBx9WPkvWDX0OIXSteCYckiQxesOfPvz26FfYxuTG/2dljDlalC+kYG05C1NEcmZWSNES
GBGfccSYSfI3Y5ahSVUhOC2LMO3JNjVyYUnOM/iyhzrnRfQoWO9GFMaugq0jBMlhZA4UO26yJqJ+BtX
IyItaEEJdc/ghIwAAAIBFeCZynstlbBjP648+mDKIvzNSS+JYr5klGxS3q8A56NPcYhDMxGn7h1DKbb
2AV4pO6y+6hDrWo3UT4dLVuzK01trwp PYp6JXTSZZ12ZaXNPz7sX9/z6pzMqhX4UEfjVsLcuF+ZS6a
QCPO0ZZEa1z+EEIZSD/ykLQsDwPxGjPBqw== someone@somewhere.com

In addition to OpenSSH and Standard SSH formats there are a variety of proprietary formats as well as SSH1 and SSH2 differences to account for, which can make this confusing.

In the example above you will note that the key starts with "ssh-dss". This is because this key was generated using DSA as opposed to RSA. A number of vendors in the SSH arena have argued, as per the PuTTY documentation that can be found at http://the.earth.li/~sgtatham/putty/0.55/htmldoc/Chapter8.html#S8.2.10 that users should employ RSA encryption because

DSA has an intrinsic weakness which makes it very easy to create a signature
which contains enough information to give away the private key! This would
allow an attacker to pretend to be you for any number of future sessions.

An SSH2 public key in OpenSSH format will start with "ssh-rsa".

The idea behind all of this is that once you have keys on the remote server and your local host, access will be simpler since the server will only grant access to someone who has the matching private key.

==Why do I need a SSH key?==

Our CVS server uses OpenSSH, so if are a Moodle developer and you want to make your logins easier (by avoiding typing in your password all the time) then you will need to submit public key in Openssh format via the "Update my developer information" tab at http://moodle.org/cvs.

==How do I create a SSH key pair?==

===Platform Independent===

Visit http://www.sshkeygen.com and simply follow the directions there.

===Eclipse===

If you plan to use Eclipse for development, please refer to the Eclipse document https://docs.moodle.org/en/Eclipse as Eclipse now has a plugin that allows you to manage all ssh key matters from within Eclipse.

===Unix/Linux===

You can use ssh-keygen at your system prompt. Please consult the man page on your system for the options available to you.

# Run: '''ssh-keygen -t (rsa or dsa)'''. This will not include a passphrase. *
# Use of rsa or dsa above will result in rsa or dsa replacing each XXX below.
# Look in your ~/.ssh directory (or wherever you saved the output). You'll find '''id_XXX''' (private) and '''id_XXX.pub''' (public).
# Cut and paste the contents of '''id_XXX.pub''' into your developer profile on http://moodle.org/cvs
# Put the private key wherever you will be calling CVS from (in your .ssh directory, for example). Make sure it's secure!

* This section initially recommended using ''ssh-keygen -d'' but it is unclear what the source of this -d option might be.

===Windows===
Use puttygen and follow the instructions [http://the.earth.li/~sgtatham/putty/0.58/htmldoc/Chapter8.html here]. Make sure you choose the RSA2 key format and that when you copy the key data into the textbox on the site, that you have all of the characters on one line. If you have opened the key with word pad, it will have line breaks in it which will stop it from working.

===Mac OS X===

Tooltips

2009-03-19T13:45:49Z

Mattgibson:

This page is aimed at listing all of the parts of Moodle that have inadequate or missing tooltips and providing suggestions for text to add to them.

Each tooltip should have three things:
* The name of the item
* How it works
* Why you would want to use it

Occasionally all 3 will not be necessary (e.g. Delete), but that should be a rare exception, not the rule.

==Course page==
Editing icons:
{| border = "1"
|-
! Icon
! Current tooltip
! Improved tooltip suggestion
|-
| Move || Move || Click here and drag to move this item to any other part of the center column
|-
| Right arrow || Move right || Click here to indent this item one level to the right. This can help you to structure your course by presenting items in nested lists
|-
| Edit icon || Update || Click here to update settings for this item such as its name or the instructions the students will see
|-
| Delete icon || Delete || Delete this item (you will be asked to confirm)
|-
| Open eye || Hide || This item is currently visible to students. Click here to hide it
|-
| Little person || No groups (click to change) || This item is currently set to 'No groups' mode, meaning that it will ignore what group(s) a student is part of. Click here to switch it to separate groups and click again to switch it to visible groups.
|-
|}

Tooltips

2009-03-19T13:39:30Z

Mattgibson: New page: This page is aimed at listing all of the parts of Moodle that have inadequate or missing tooltips and providing suggestions for text to add to them ==Course page== Editing icons: {| borde...

This page is aimed at listing all of the parts of Moodle that have inadequate or missing tooltips and providing suggestions for text to add to them

==Course page==
Editing icons:
{| border = "1"
|-
! Icon
! Current tooltip
! Improved tooltip suggestion
|-
| Move || Move || Click here and drag to move this item to any other part of the center column
|-
| Right arrow || Move right || Click here to indent this item one level to the right. This can help you to structure your course by presenting items in nested lists
|-
| Edit icon || Update || Click here to update settings for this item such as its name or the instructions the students will see
|-
| Delete icon || Delete || Delete this item (you will be asked to confirm)
|-
| Open eye || Hide || This item is currently visible to students. Click here to hide it
|-
| Little person || No groups (click to change) || This item is currently set to 'No groups' mode, meaning that it will ignore what group(s) a student is part of. Click here to switch it to separate groups and click again to switch it to visible groups.
|-
|}

Talk:Gradebook improvements

2009-01-22T13:36:37Z

Mattgibson: /* Common frustrations */

==Aggregation of hidden grades==

Overlook problem partially solve after the database freeze - workaround was to recalculate the grades on the fly so that users that can the hidden grades are ignored. This approach is expensive and can not be used in conditional activities, grade exports, etc.

Solution is to add new flag into grade categories - aggregate hidden grades. Having two values for each grade would be too complex, selective agrragation should solve most of the problems and should be reasonably backwards compatible.

--[[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 11:56, 8 December 2008

==Exports: more flexibility==

Two aspects of the 1.9 export plugin have been criticised by some of Catalyst's clients:

* the fact that grade exports are tied to a course
* the default user profile columns are not all needed and some custom ones would be necessary

Therefore I propose the following changes:

* removing the export plugin dependency on a single course by converting to an array of courses (see MDL-17420)
* making the user-related columns customisable (see MDL-17346)

--[[User:Francois Marier|Francois Marier]] 06:42, 9 December 2008

==Gradebook does not consider groupings functionality==

Student in gradebook view all grade items, but must view only grade items thats belong to his groiping (see MDL-13868).

--[[User:Artem Andreev|Artem Andreev]] 11:07, 9 December 2008

==Common frustrations==
Below are some of the most often reported usability issues in the 1.9 gradebook, which we are trying to address. Several of these are grouped as sub-tasks under MDL-16913.

===Assigning weights to categories and grade items===
This is the most common frustration. Weights are used extensively in many institutions, and were used in 1.8. However, they are difficult to understand in 1.9, and difficult to set up. This issue is discussed extensively in MDL-15680.

===Moving items to categories===
Currently, the [[Edit categories and items]] page lets you move only one grade item or category at a time. It takes two page refreshes and two mouse clicks per move. This is very tedious and time-consuming when many items have to be moved around. MDL-13775 and MDL-12502 address this problem.

===Removing the ''overridden'' attribute of individual grades===
When grades are imported into an existing gradebook, or when grades are manually edited in the grader report, these grades become [[Grade_editing#Overridden|overridden]], which prevents linked activity modules from updating this grade. Removing this attribute is very time-consuming, since one must enter the edit page of each individual grade, untick the checkbox and submit the form. This issue is discussed in [http://moodle.org/mod/forum/discuss.php?d=109636 this forum thread].

===Viewing the overall contribution of each category and item to the course aggregation===
The tracker issue MDL-13777 reports the difficulty in seeing the contribution of each grade item and category to the course total. Calculations and weights may apply, which are not visible in any of the current reports except in each individual category or item's edit page.

--[[User:Nicolas Connault|Nicolas Connault]] 12:41, 4 November 2008

Some more that it would be great to see fixed:
===Setting grade to pass===
Takes a lot of clicks and the edit icon looks like it's part of the main mass of editing icons for the grades table itself, so it's hard to find. This is a very useful feature (at least once MDL-13830 is fixed) as it shows at a glance how many items a student has failed to pass. Seeing a row of red entries is a great way of quickly knowing who to target for extra attention in class. Quite obscure at the moment though, especially seeing as it cannot be done from the module itself. -[[User:Matt Gibson|Matt Gibson]] 07:36, 22 January 2009 (CST)

===Its not possible to see whether or not a student has submitted work which has not been marked===
If the modules could send a special grade e.g. -1 to the gradebook as a placeholder that could be used to add either a css class to a cell, or display a special character to show that work is waiting. Then it would be possible to use the gradebook like a normal one, in order to evaluate students' deadline-meeting for writing reports. At the moment, this is probably the biggest problem in our institution's use of the gradebook. - [[User:Matt Gibson|Matt Gibson]] 07:36, 22 January 2009 (CST)

==Patch for Edit Categories and Items page==
Following is a proposed patch to the '''Edit categories and items''' page in the 1.9 gradebook. It addresses many usability issues while remaining simple. The following features are currently implemented:

===Simple features===
[[Image:gradebook_categories_simple.png|600px]]
*Items and categories are displayed in a table instead of a list. This improves readability and will make drag and drop easier to implement.
*All advanced features are hidden by default, so that the interface by default is almost identical to the original
*An additional column has checkboxes for grade items. All selected items can then be moved to one of the existing grade categories for the current course. Javascript "Select all/Select None" links replace these checkboxes for categories, to make it faster to select or de-select items.

===Advanced features===
[[Image:gradebook_categories_advanced.png|600px]]

*[[Category aggregation|Grade category aggregation type]]: changing this reloads the page, because the grade item weights/extra credits only apply to some of these aggregation types.
*Weight or extra credit: depending on the parent category's aggregation type, each category and grade item may have an input field or a checkbox for weight or extra credit. All these can be edited, then submitted with one click.
*Grade range is displayed for information purposes, but cannot be edited through this interface (it is most often controlled by the linked activity)
*[[Grade_categories#Aggregate_only_non-empty_grades|Aggregate only non-empty grades]]
*[[Grade_categories#Aggregate_including_sub-categories|Aggregate including sub-categories]]
*[[Grade_categories#Include_outcomes_in_aggregation|Include outcomes in aggregation]]
*[[Grade_categories#Drop_the_lowest|Drop the lowest]]
*[[Grade_categories#Keep_the_highest|Keep the highest]]
*[[Grade items|Multiplicator]]
*[[Grade_items|Offset]]

All these settings can be changed then submitted with only one page reload. Just be mindful that changing a category's aggregation type will reload the page and you will lose any non-submitted changes you made to the other settings.

--[[User:Nicolas Connault|Nicolas Connault]] 12:41, 4 November 2008

==See also==

* [[Tim's_Gradebook_thoughts|Tim's Gradebook thoughts]]