MoodleDocs - User contributions [en]

Development:Themes 2.0 creating your first theme

2011-05-27T09:04:59Z

Howardsmiller: /* Configuring the language file */

{{Template:Themes}}{{Moodle 2.0}}This document describes how to create a theme for Moodle 2.0. It assumes you have some understanding of how themes within Moodle work as well as a good understanding of HTML and CSS.

===Theme designer mode===

Under normal operation Moodle does several things in the name of performance, one of these is to combine all of the CSS into one file, minimize it, cache it on the server, and then serve it. After the first request the cached version is served to greatly improve page performance.

What this means for you as a themer? When you make changes they will not be seen immediately. In fact you will need to tell Moodle to rebuild the cache that it is serving.
This isn't practical for designing themes of course so the '''theme designer mode''' was added. When enabled it tells Moodle not to combine or cache the CSS that gets delivered. This has the downside that page load times will take significantly longer, however you will see your changes immediately every time.

Theme designer mode may be enabled via ''Administration > Appearance > Themes > [[Theme settings]]''.

'''Warning''': Internet Explorer versions 6 and 7 have BIG problems when a site attempts to link to more than 31 stylesheets, in which case either a limited number or no styles get applied. Because Moodle sends up all of the CSS all of the time with theme designer mode turned on there is a very high chance you will get more than 31 stylesheets being included. This will, of course, cause major problems for Internet Explorer until theme designer mode is turned off.

==Getting started==

The first thing you need to do is create the directories and files you will be using, the first thing to create is the actual directory for your theme. This should be the name of your theme, in my case it's 'excitement'. The directory should be located within the theme directory of Moodle, ./moodle/theme/excitement/ will be the directory I create.

Now within that directory we can immediately create several files that we know we are going to need.

So the files that we want to create are:
; config.php : All of our settings will go here.
; /style/ : This directory will contain all of our stylesheets.
; /style/excitement.css : All of our css will go in here.
; /pix/ : Into this directory we'll put a screen shot of our theme as well as our favicon and any images we use in CSS.
; /layout/ : Our layout files will end up in this directory.
; /layout/standard.php : This will be our one basic layout file.
; /lang/en/ : The file we put here will make our theme name show properly on the Theme Selector page. You need a few standard entries. Copy the one from the Standard theme and modify is easiest.

So after this setup step you should have a directory structure similar to what is shown below.

[[image:Learn_to_theme_01.jpg]]

==Configuring our theme==

Open config.php in your favourite editor and start by adding the opening PHP tags '''<nowiki><?php</nowiki>'''.

Now we need to add the settings:

<code php>
$THEME->name = 'excitement';
</code>
Very simply this tells Moodle the name of your theme, and if you ever have several config.php files open this will help you identify which one you are looking at.

Next, the parents for this theme.
<code php>
$THEME->parents = array('base');
</code>
This tells Moodle that my new theme ''`excitement`' wants to extend the base theme.

A theme can extend any number of themes. Rather than creating an entirely new theme and copying all of the CSS, you can simply create a new theme, extend the theme you like and just add the changes you want to your theme.

Also worth noting is the purpose of the base theme: it provides us with a basic layout and just enough CSS to make everything fall into place.

Now we will tell Moodle about our stylesheets:
<code php>
$THEME->sheets = array('excitement');
</code>

The final thing we need to add into our theme's config.php file is the definition of the layouts for our theme:
<code php>
$THEME->layouts = array(
'base' => array(
'file' => 'standard.php',
'regions' => array(),
),
'standard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'course' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
),
'coursecategory' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'incourse' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'frontpage' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'admin' => array(
'file' => 'standard.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
'mydashboard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'mypublic' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),
'popup' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'frametop' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'maintenance' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true),
),
'print' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>false),
),
);

/** List of javascript files that need to be included on each page */
$THEME->javascripts = array();
$THEME->javascripts_footer = array();

</code>

What you are looking at is the different layouts for our theme. Why are there so many? Because, that is how many there are in Moodle. There is one for every general type of page. With my ''`excitement`'' theme I have chosen to use my own layout. Unless there was a specific reason to do so, normally you would not need to create your own layouts, you could extend the base theme, and use its layouts, meaning you would only have to write CSS to achieve your desired look.

For each layout above, you will notice the following four things are being set:
; file : This is the name of the layout file we want to use, it should always be located in the above themes layout directory. For us this is of course standard.php as we only have one layout file.
; regions : This is an array of block regions that our theme has. Each entry in here can be used to put blocks in when that layout is being used.
; defaultregion : If a layout has regions it should have a default region, this is where blocks get put when first added.
; options : These are special settings, anything that gets put into the options array is available later on when we are writing our layout file.

There are additional settings that can be defined in the config.php file - see [[Development:Themes 2.0|Themes 2.0]] for the full list.

==Configuring the language file==
Open theme_base.php file from '''base/lang/en/theme_base.php'''

Save it as '''excitement/lang/en/theme_excitement.php'''.

Change
<code php>
$string['pluginname'] = 'Base';
</code>
to
<code php>
$string['pluginname'] = 'Excitement';
</code>

After making these changes and perhaps clearing theme caches and/or purging all caches, the new theme name should now show properly in the Theme Selector: ''Site Administration > Appearance > Themes > Theme Selector''

You can also edit the theme description:

<code php>
$string['choosereadme'] = 'Write your theme description here.';
</code>

You need to leave the following two lines in place (you can change the wording if you need to) to avoid notices when editing blocks etc.:

<code php>
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
</code>

==Writing the layout file==

The excitement theme has just one layout file.

The downside of this is that I have to make the layout file do everything I want which means I need to make use of some options (as defined in the layouts in config.php).

The upside is that I only need to maintain one file.

Other than maintenance, using multiple layout files provides many advantages to real world themes in that you can easily tweak and customise specific layouts to achieve the goals of the organisation using the theme.

So lets start writing standard.php, the layout file for my ''`excitement`'' theme.

===The top of the layout file===

<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype(); ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
</code>

Lets look at the code that goes into this section:
<code php>
<?php
echo $OUTPUT->doctype(); ?>
</code>
This is very important and is required to go at the very top of the page. This tells Moodle to print out the document type tag that is determined by the settings within Moodle.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we open the HTML tag and then ask Moodle to print the attributes that should go inside it.

<code php>
<title><?php echo $PAGE->title ?></title>
</code>
Simply creates the title tag and asks Moodle to fill it in.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
Here we are asking Moodle to print all of the other tags and content that need to go into the head. This includes stylesheets, script tags, and inline JavaScript code.

===The page header===

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
<?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>
</code>

So there is a bit more going on here obviously.

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
</code>
Again much like what we did for the opening HTML tag in the head we have started writing the opening body tag and are then asking Moodle to give us the ID we should use for the body tag as well as the classes we should use.

<code php>
<?php echo $OUTPUT->standard_top_of_body_html() ?>
</code>
This very important call writes some critical bits of JavaScript into the page. It should always be located after the body tag as soon as possible.

<code php>
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
......
<?php } ?>
</code>
Here we are checking whether or not we need to print the header for the page. There are three checks we need to make here:
# '''$PAGE->heading''' : This checks to make sure that there is a heading for the page. This will have been set by the script and normally describes the page in a couple of words.
# '''empty($PAGE->layout_options['nonavbar'])''' : Now this check is looking at the layout options that we set in our config.php file. It is looking to see if the layout set 'nonavbar' => true.
# '''$PAGE->has_navbar()''' The third check is to check with the page whether it has a navigation bar to display.
If either there is a heading for this page or there is a navigation bar to display then we will display a heading.

Leading on from this lets assume that there is a header to print.
<code php>
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
.....
<?php } ?>
</code>
This line is simply saying if the page has a heading print it. In this case we run the first check above again just to make sute there is a heading, we then open a heading tag that we choose and ask the page to print the heading.

<code php>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
</code>
Here we are looking to print the menu and content that you see at the top of the page (usually to the right). We start by getting Moodle to print the login information for the current user. If the user is logged in this will be their name and a link to their profile, if not then it will be a link to login.

Next we check our page options to see whether a language menu should be printed. If in the layout definition within config.php it sets '''langmenu => true''' then we will print the language menu, a drop down box that lets the user change the language that Moodle displays in.

Finally the page also has a heading menu that can be printed. This heading menu is special HTML that the page you are viewing wants to add. It can be anything from drop down boxes to buttons and any number of each.

<code php>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
The final part of the header.

Here we want to print the navigation bar for the page if there is one. To find out if there is one we run checks number 2 and 3 again and proceed if they pass.

Assuming there is a header then there are two things that we need to print. The first is the navigation bar. This is a component that the OUTPUT library knows about. The second is a button to shown on the page.

In both cases we can choose to wrap them in a div to make our life as a themer easier.

Well that is it for the header. There is a lot of PHP compared to the other sections of the layout file but it does not change and can be copied and pasted between themes.

===The page content===

I am going with the default two block regions plus the main content.

Because I have based this theme and layout file on the base theme the HTML looks a little intense. This is because it is a floating div layout where the content comes first and then we get the columns (even though one column will be to the left of the content.) Don't worry too much about it. When it comes to writing your own theme you can go about it as you choose.

<code php>
<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>
</code>

In regards to PHP this section is very easy. There are only three lines for the whole section one to get the main content and one for each block region.
<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This line prints the main content for the page.

<code php>
<?php if ($hassidepre) { ?>
....
<?php } ?>
</code>
These lines of code check the variables we created earlier on to decide whether we should show the pre block region. If you try to display a block region that isn't there or has no content then Moodle will give you an error message so these lines are very important.

For those who get an error message if it is "unknown block region side-pre" or "unknown block region side-post" then this is the issue you are experiencing. Simply add the following lines and all will be fine.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
This line gets all of the blocks and more particularly the content for the block region '''side-pre'''. This block region will be displayed to the left of the content.

<code php>
<?php if ($hassidepost) { ?>
....
<?php } ?>
</code>
Again we should make this check for every block region as there are some pages that have no blocks what-so-ever.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we are getting the other block region '''side-post''' which will be displayed to the right of the content.

===The page footer===
Here we want to print the footer for the page, any content required by Moodle, and then close the last tags.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

The section of code is responsible for printing the footer for the page.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</code>
The first thing we do before printing the footer is check that we actually want to print it. This is done by checking the options for the layout as defined in the config.php file. If '''nofooter => true''' is set the we don't want to print the footer and should skip over this body of code.

Assuming we want to print a footer we proceed to create a div to house its content and then print the bits of the content that will make it up.
There are four things that the typical page footer will want to print:
; echo page_doc_link(get_string('moodledocslink')) : This will print a link to the Moodle.org help page for this particular page.
; echo $OUTPUT->login_info(); : This is the same as at the top of the page and will print the login information for the current user.
; echo $OUTPUT->home_link(); : This prints a link back to the Moodle home page for this site.
; echo $OUTPUT->standard_footer_html(); : This prints special HTML that is determined by the settings for the site. Things such as performance information or debugging will be printed by this line if they are turned on.

And the final line of code for our layout file is:
<code php>
<?php echo $OUTPUT->standard_end_of_body_html(); ?>
</code>
This is one of the most important lines of code in the layout file. It asks Moodle to print any required content into the page, and there will likely be a lot although most of it will not be visual.

It will instead be things such as inline scripts and JavaScript files required to go at the bottom of the page. If you forget this line its likely no JavaScript will work!

We've now written our layout file and it is all set to go. The complete source is below for reference. Remember if you want more practical examples simply look at the layout files located within the layout directory of other themes.

<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title; ?></title>
<link rel="shortcut icon" href="<?php echo $OUTPUT->pix_url('favicon', 'theme')?>" />
<?php echo $OUTPUT->standard_head_html() ?>
</head>

<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div><?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>

<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>

<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

==Adding some CSS==
With config.php and standard.php both complete the theme is now usable and starting to look like a real theme, however if you change to it using the theme selector you will notice that it still lacks any style.

This of course is where CSS comes in. When writing code Moodle developers are strongly encouraged to not use inline styles anywhere. This is fantastic for us as themers because there is nothing (or at least very little) in Moodle that cannot be styled using CSS.

===Moodle CSS basics===

In Moodle 2.0 all of the CSS for the whole of Moodle is delivered all of the time! This was done for performance reasons. Moodle now reads in all of the CSS, combines it into one file, shrinks it removing any white space, caches it, and then delivers it.

'''What this means for you as a themer?'''

You will need to write good CSS that won't clash with any other CSS within Moodle.

Moodle is so big and complex,there is no way to ensure that classes don't get reused. What we can control however is the classes and id that get added to the body tag for every page. When writing CSS it is highly encouraged to make full use of these body classes, using them will help ensure the CSS you write has the least chance of causing conflicts.

You should also take the time to look at how the Moodle themes use CSS. Look at their use of the body classes and how they separate the CSS for the theme into separate files based on the region of Moodle it applies to.

Check out [[Development:Themes 2.0|Themes 2.0]] for more information about writing good CSS.

===Starting to write excitement.css===

<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.navbar {padding-left: 1em;}
.breadcrumb li {color: #FFF;}
.breadcrumb li a {color: #FFF;}

.block {background-color: #013D6A;}
.block .header .title {color: #FFF;}
.block .header .title .block_action input {background-color: #FFF;}
.block .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.block .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}
</code>
[[image:Learn_to_theme_02.jpg|400px|thumb|Excitement theme screenshot]]
This isn't all of the CSS for the theme, but just enough to style the front page when the user is not logged in.
Remember this theme extends the base theme so there is already CSS for layout as well.

Note:
* The CSS is laid out in a single line format. This is done within the core themes for Moodle. It makes it quicker to read the selectors and see what is being styled.
* I have written my selectors to take into account the structure of the HTML (more than just the one tag I want to style). This helps further to reduce the conflicts that I may encounter.
* I use generic classes like ''.sideblock'' only where I want to be generic, as soon as I want to be specific I use the unique classes such as ''.block_calendar_month''

<br style="clear:right;" />

===Using images within CSS===

I will add two image files to the pix directory of my theme:
; /theme/excitement/pix/background.png : This will be the background image for my theme.
; /theme/excitement/pix/gradient.jpg : This will be a gradient I use for the header and headings.
I quickly created both of these images using gimp and simply saved them to the pix directory.
<code css>
html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);background-repeat:repeat-x;background-color: #0273C8;}
</code>
[[image:Learn_to_theme_03.jpg‎|400px|thumb|Excitement theme screenshot]]
The CSS above is the two new rules that I had to write to use my images within CSS.

The first rule sets the background image for the page to background.png

The second rule sets the background for headings, and the sideblocks to use gradient.jpg

You will notice that I did not need to write a path to the image. This is because Moodle has this special syntax that can be used and will be replaced when the CSS is parsed before delivery.
The advantage of using this syntax over writing the path in is that the path may change depending on where you are or what theme is being used.

Other themers may choose to extend your theme with their own; if you use this syntax then all they need to do to override the image is to create one with the same name in their themes directory.

You will also notice that I don't need to add the image files extension. This is because Moodle is smart enough to work out what extension the file uses. It also allows themers to override images with different formats.

<br style="clear:right" />
The following is the complete CSS for my theme:
<div style="overflow:auto;height:860px;">
<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;border-bottom:5px solid #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.sideblock {background-color: #013D6A;}
.sideblock .header .title {color: #FFF;}
.sideblock .header .title .block_action input {background-color: #FFF;}
.sideblock .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.sideblock .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}

html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);
background-repeat:repeat-x;background-color: #0273C8;}
</code>
</div>

==Adding a screenshot and favicon==
The final thing to do at this point is add both a screenshot for this theme as well as a favicon for it.
The screenshot will be shown in the theme selector screen and should be named ''screenshot.jpg''.
The favicon will be used when someone bookmarks this page.
Both images should be located in your themes pix directory as follows:
* /theme/excitement/pix/screenshot.jpg
* /theme/excitement/pix/favicon.ico

In the case of my theme I have taken a screenshot and added it to that directory, and because I don't really want to do anything special with the favicon I have copied it from /theme/base/pix/favicon.ico so that at least it will be recognisable as Moodle.

==See also==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 overriding a renderer]]

[[Category:Themes]]
[[es:Desarollo:Temas 2.0 creando tu primer tema]]

Development:Themes 2.0 creating your first theme

2011-05-27T09:03:16Z

Howardsmiller: /* Getting started */

{{Template:Themes}}{{Moodle 2.0}}This document describes how to create a theme for Moodle 2.0. It assumes you have some understanding of how themes within Moodle work as well as a good understanding of HTML and CSS.

===Theme designer mode===

Under normal operation Moodle does several things in the name of performance, one of these is to combine all of the CSS into one file, minimize it, cache it on the server, and then serve it. After the first request the cached version is served to greatly improve page performance.

What this means for you as a themer? When you make changes they will not be seen immediately. In fact you will need to tell Moodle to rebuild the cache that it is serving.
This isn't practical for designing themes of course so the '''theme designer mode''' was added. When enabled it tells Moodle not to combine or cache the CSS that gets delivered. This has the downside that page load times will take significantly longer, however you will see your changes immediately every time.

Theme designer mode may be enabled via ''Administration > Appearance > Themes > [[Theme settings]]''.

'''Warning''': Internet Explorer versions 6 and 7 have BIG problems when a site attempts to link to more than 31 stylesheets, in which case either a limited number or no styles get applied. Because Moodle sends up all of the CSS all of the time with theme designer mode turned on there is a very high chance you will get more than 31 stylesheets being included. This will, of course, cause major problems for Internet Explorer until theme designer mode is turned off.

==Getting started==

The first thing you need to do is create the directories and files you will be using, the first thing to create is the actual directory for your theme. This should be the name of your theme, in my case it's 'excitement'. The directory should be located within the theme directory of Moodle, ./moodle/theme/excitement/ will be the directory I create.

Now within that directory we can immediately create several files that we know we are going to need.

So the files that we want to create are:
; config.php : All of our settings will go here.
; /style/ : This directory will contain all of our stylesheets.
; /style/excitement.css : All of our css will go in here.
; /pix/ : Into this directory we'll put a screen shot of our theme as well as our favicon and any images we use in CSS.
; /layout/ : Our layout files will end up in this directory.
; /layout/standard.php : This will be our one basic layout file.
; /lang/en/ : The file we put here will make our theme name show properly on the Theme Selector page. You need a few standard entries. Copy the one from the Standard theme and modify is easiest.

So after this setup step you should have a directory structure similar to what is shown below.

[[image:Learn_to_theme_01.jpg]]

==Configuring our theme==

Open config.php in your favourite editor and start by adding the opening PHP tags '''<nowiki><?php</nowiki>'''.

Now we need to add the settings:

<code php>
$THEME->name = 'excitement';
</code>
Very simply this tells Moodle the name of your theme, and if you ever have several config.php files open this will help you identify which one you are looking at.

Next, the parents for this theme.
<code php>
$THEME->parents = array('base');
</code>
This tells Moodle that my new theme ''`excitement`' wants to extend the base theme.

A theme can extend any number of themes. Rather than creating an entirely new theme and copying all of the CSS, you can simply create a new theme, extend the theme you like and just add the changes you want to your theme.

Also worth noting is the purpose of the base theme: it provides us with a basic layout and just enough CSS to make everything fall into place.

Now we will tell Moodle about our stylesheets:
<code php>
$THEME->sheets = array('excitement');
</code>

The final thing we need to add into our theme's config.php file is the definition of the layouts for our theme:
<code php>
$THEME->layouts = array(
'base' => array(
'file' => 'standard.php',
'regions' => array(),
),
'standard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'course' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
),
'coursecategory' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'incourse' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'frontpage' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'admin' => array(
'file' => 'standard.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
'mydashboard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'mypublic' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),
'popup' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'frametop' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'maintenance' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true),
),
'print' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>false),
),
);

/** List of javascript files that need to be included on each page */
$THEME->javascripts = array();
$THEME->javascripts_footer = array();

</code>

What you are looking at is the different layouts for our theme. Why are there so many? Because, that is how many there are in Moodle. There is one for every general type of page. With my ''`excitement`'' theme I have chosen to use my own layout. Unless there was a specific reason to do so, normally you would not need to create your own layouts, you could extend the base theme, and use its layouts, meaning you would only have to write CSS to achieve your desired look.

For each layout above, you will notice the following four things are being set:
; file : This is the name of the layout file we want to use, it should always be located in the above themes layout directory. For us this is of course standard.php as we only have one layout file.
; regions : This is an array of block regions that our theme has. Each entry in here can be used to put blocks in when that layout is being used.
; defaultregion : If a layout has regions it should have a default region, this is where blocks get put when first added.
; options : These are special settings, anything that gets put into the options array is available later on when we are writing our layout file.

There are additional settings that can be defined in the config.php file - see [[Development:Themes 2.0|Themes 2.0]] for the full list.

==Configuring the language file==
Open theme_base.php file from '''base/lang/en/theme_base.php'''

Save it as '''excitement/lang/en/theme_excitement.php'''.

Change
<code php>
$string['pluginname'] = 'Base';
</code>
to
<code php>
$string['pluginname'] = 'Excitement';
</code>

After making these changes and perhaps clearing theme caches and/or purging all caches, the new theme name should now show properly in the Theme Selector: ''Site Administration > Appearance > Themes > Theme Selector''

You can also edit the theme description:

<code php>
$string['choosereadme'] = 'Write your theme description here.';
</code>

==Writing the layout file==

The excitement theme has just one layout file.

The downside of this is that I have to make the layout file do everything I want which means I need to make use of some options (as defined in the layouts in config.php).

The upside is that I only need to maintain one file.

Other than maintenance, using multiple layout files provides many advantages to real world themes in that you can easily tweak and customise specific layouts to achieve the goals of the organisation using the theme.

So lets start writing standard.php, the layout file for my ''`excitement`'' theme.

===The top of the layout file===

<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype(); ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
</code>

Lets look at the code that goes into this section:
<code php>
<?php
echo $OUTPUT->doctype(); ?>
</code>
This is very important and is required to go at the very top of the page. This tells Moodle to print out the document type tag that is determined by the settings within Moodle.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we open the HTML tag and then ask Moodle to print the attributes that should go inside it.

<code php>
<title><?php echo $PAGE->title ?></title>
</code>
Simply creates the title tag and asks Moodle to fill it in.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
Here we are asking Moodle to print all of the other tags and content that need to go into the head. This includes stylesheets, script tags, and inline JavaScript code.

===The page header===

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
<?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>
</code>

So there is a bit more going on here obviously.

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
</code>
Again much like what we did for the opening HTML tag in the head we have started writing the opening body tag and are then asking Moodle to give us the ID we should use for the body tag as well as the classes we should use.

<code php>
<?php echo $OUTPUT->standard_top_of_body_html() ?>
</code>
This very important call writes some critical bits of JavaScript into the page. It should always be located after the body tag as soon as possible.

<code php>
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
......
<?php } ?>
</code>
Here we are checking whether or not we need to print the header for the page. There are three checks we need to make here:
# '''$PAGE->heading''' : This checks to make sure that there is a heading for the page. This will have been set by the script and normally describes the page in a couple of words.
# '''empty($PAGE->layout_options['nonavbar'])''' : Now this check is looking at the layout options that we set in our config.php file. It is looking to see if the layout set 'nonavbar' => true.
# '''$PAGE->has_navbar()''' The third check is to check with the page whether it has a navigation bar to display.
If either there is a heading for this page or there is a navigation bar to display then we will display a heading.

Leading on from this lets assume that there is a header to print.
<code php>
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
.....
<?php } ?>
</code>
This line is simply saying if the page has a heading print it. In this case we run the first check above again just to make sute there is a heading, we then open a heading tag that we choose and ask the page to print the heading.

<code php>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
</code>
Here we are looking to print the menu and content that you see at the top of the page (usually to the right). We start by getting Moodle to print the login information for the current user. If the user is logged in this will be their name and a link to their profile, if not then it will be a link to login.

Next we check our page options to see whether a language menu should be printed. If in the layout definition within config.php it sets '''langmenu => true''' then we will print the language menu, a drop down box that lets the user change the language that Moodle displays in.

Finally the page also has a heading menu that can be printed. This heading menu is special HTML that the page you are viewing wants to add. It can be anything from drop down boxes to buttons and any number of each.

<code php>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
The final part of the header.

Here we want to print the navigation bar for the page if there is one. To find out if there is one we run checks number 2 and 3 again and proceed if they pass.

Assuming there is a header then there are two things that we need to print. The first is the navigation bar. This is a component that the OUTPUT library knows about. The second is a button to shown on the page.

In both cases we can choose to wrap them in a div to make our life as a themer easier.

Well that is it for the header. There is a lot of PHP compared to the other sections of the layout file but it does not change and can be copied and pasted between themes.

===The page content===

I am going with the default two block regions plus the main content.

Because I have based this theme and layout file on the base theme the HTML looks a little intense. This is because it is a floating div layout where the content comes first and then we get the columns (even though one column will be to the left of the content.) Don't worry too much about it. When it comes to writing your own theme you can go about it as you choose.

<code php>
<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>
</code>

In regards to PHP this section is very easy. There are only three lines for the whole section one to get the main content and one for each block region.
<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This line prints the main content for the page.

<code php>
<?php if ($hassidepre) { ?>
....
<?php } ?>
</code>
These lines of code check the variables we created earlier on to decide whether we should show the pre block region. If you try to display a block region that isn't there or has no content then Moodle will give you an error message so these lines are very important.

For those who get an error message if it is "unknown block region side-pre" or "unknown block region side-post" then this is the issue you are experiencing. Simply add the following lines and all will be fine.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
This line gets all of the blocks and more particularly the content for the block region '''side-pre'''. This block region will be displayed to the left of the content.

<code php>
<?php if ($hassidepost) { ?>
....
<?php } ?>
</code>
Again we should make this check for every block region as there are some pages that have no blocks what-so-ever.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we are getting the other block region '''side-post''' which will be displayed to the right of the content.

===The page footer===
Here we want to print the footer for the page, any content required by Moodle, and then close the last tags.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

The section of code is responsible for printing the footer for the page.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</code>
The first thing we do before printing the footer is check that we actually want to print it. This is done by checking the options for the layout as defined in the config.php file. If '''nofooter => true''' is set the we don't want to print the footer and should skip over this body of code.

Assuming we want to print a footer we proceed to create a div to house its content and then print the bits of the content that will make it up.
There are four things that the typical page footer will want to print:
; echo page_doc_link(get_string('moodledocslink')) : This will print a link to the Moodle.org help page for this particular page.
; echo $OUTPUT->login_info(); : This is the same as at the top of the page and will print the login information for the current user.
; echo $OUTPUT->home_link(); : This prints a link back to the Moodle home page for this site.
; echo $OUTPUT->standard_footer_html(); : This prints special HTML that is determined by the settings for the site. Things such as performance information or debugging will be printed by this line if they are turned on.

And the final line of code for our layout file is:
<code php>
<?php echo $OUTPUT->standard_end_of_body_html(); ?>
</code>
This is one of the most important lines of code in the layout file. It asks Moodle to print any required content into the page, and there will likely be a lot although most of it will not be visual.

It will instead be things such as inline scripts and JavaScript files required to go at the bottom of the page. If you forget this line its likely no JavaScript will work!

We've now written our layout file and it is all set to go. The complete source is below for reference. Remember if you want more practical examples simply look at the layout files located within the layout directory of other themes.

<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title; ?></title>
<link rel="shortcut icon" href="<?php echo $OUTPUT->pix_url('favicon', 'theme')?>" />
<?php echo $OUTPUT->standard_head_html() ?>
</head>

<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div><?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>

<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>

<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

==Adding some CSS==
With config.php and standard.php both complete the theme is now usable and starting to look like a real theme, however if you change to it using the theme selector you will notice that it still lacks any style.

This of course is where CSS comes in. When writing code Moodle developers are strongly encouraged to not use inline styles anywhere. This is fantastic for us as themers because there is nothing (or at least very little) in Moodle that cannot be styled using CSS.

===Moodle CSS basics===

In Moodle 2.0 all of the CSS for the whole of Moodle is delivered all of the time! This was done for performance reasons. Moodle now reads in all of the CSS, combines it into one file, shrinks it removing any white space, caches it, and then delivers it.

'''What this means for you as a themer?'''

You will need to write good CSS that won't clash with any other CSS within Moodle.

Moodle is so big and complex,there is no way to ensure that classes don't get reused. What we can control however is the classes and id that get added to the body tag for every page. When writing CSS it is highly encouraged to make full use of these body classes, using them will help ensure the CSS you write has the least chance of causing conflicts.

You should also take the time to look at how the Moodle themes use CSS. Look at their use of the body classes and how they separate the CSS for the theme into separate files based on the region of Moodle it applies to.

Check out [[Development:Themes 2.0|Themes 2.0]] for more information about writing good CSS.

===Starting to write excitement.css===

<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.navbar {padding-left: 1em;}
.breadcrumb li {color: #FFF;}
.breadcrumb li a {color: #FFF;}

.block {background-color: #013D6A;}
.block .header .title {color: #FFF;}
.block .header .title .block_action input {background-color: #FFF;}
.block .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.block .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}
</code>
[[image:Learn_to_theme_02.jpg|400px|thumb|Excitement theme screenshot]]
This isn't all of the CSS for the theme, but just enough to style the front page when the user is not logged in.
Remember this theme extends the base theme so there is already CSS for layout as well.

Note:
* The CSS is laid out in a single line format. This is done within the core themes for Moodle. It makes it quicker to read the selectors and see what is being styled.
* I have written my selectors to take into account the structure of the HTML (more than just the one tag I want to style). This helps further to reduce the conflicts that I may encounter.
* I use generic classes like ''.sideblock'' only where I want to be generic, as soon as I want to be specific I use the unique classes such as ''.block_calendar_month''

<br style="clear:right;" />

===Using images within CSS===

I will add two image files to the pix directory of my theme:
; /theme/excitement/pix/background.png : This will be the background image for my theme.
; /theme/excitement/pix/gradient.jpg : This will be a gradient I use for the header and headings.
I quickly created both of these images using gimp and simply saved them to the pix directory.
<code css>
html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);background-repeat:repeat-x;background-color: #0273C8;}
</code>
[[image:Learn_to_theme_03.jpg‎|400px|thumb|Excitement theme screenshot]]
The CSS above is the two new rules that I had to write to use my images within CSS.

The first rule sets the background image for the page to background.png

The second rule sets the background for headings, and the sideblocks to use gradient.jpg

You will notice that I did not need to write a path to the image. This is because Moodle has this special syntax that can be used and will be replaced when the CSS is parsed before delivery.
The advantage of using this syntax over writing the path in is that the path may change depending on where you are or what theme is being used.

Other themers may choose to extend your theme with their own; if you use this syntax then all they need to do to override the image is to create one with the same name in their themes directory.

You will also notice that I don't need to add the image files extension. This is because Moodle is smart enough to work out what extension the file uses. It also allows themers to override images with different formats.

<br style="clear:right" />
The following is the complete CSS for my theme:
<div style="overflow:auto;height:860px;">
<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;border-bottom:5px solid #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.sideblock {background-color: #013D6A;}
.sideblock .header .title {color: #FFF;}
.sideblock .header .title .block_action input {background-color: #FFF;}
.sideblock .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.sideblock .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}

html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);
background-repeat:repeat-x;background-color: #0273C8;}
</code>
</div>

==Adding a screenshot and favicon==
The final thing to do at this point is add both a screenshot for this theme as well as a favicon for it.
The screenshot will be shown in the theme selector screen and should be named ''screenshot.jpg''.
The favicon will be used when someone bookmarks this page.
Both images should be located in your themes pix directory as follows:
* /theme/excitement/pix/screenshot.jpg
* /theme/excitement/pix/favicon.ico

In the case of my theme I have taken a screenshot and added it to that directory, and because I don't really want to do anything special with the favicon I have copied it from /theme/base/pix/favicon.ico so that at least it will be recognisable as Moodle.

==See also==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 overriding a renderer]]

[[Category:Themes]]
[[es:Desarollo:Temas 2.0 creando tu primer tema]]

Development:Themes 2.0

2011-05-27T09:01:52Z

Howardsmiller: /* Layout files */

{{Template:Themes}}{{Moodle 2.0}}Welcome to the new world of themes within Moodle 2.0!

This document explains how themes work in Moodle and is intended to help you create or modify most themes for Moodle 2.0.

==Introduction==

Moodle themes are responsible for much of the "look" of a Moodle site. They provide the CSS for colours, layouts, fonts and so on, and can also change the structural XHTML code below that.

A theme can either contain all the definitions (completely stand alone) or it can extend an existing theme with one or more customizations.

Most theme developers use the second method and simply add a few new CSS or layout definitions to their new theme. If a definition or element is not found in the new theme, it looks to the "parent" (or up the hierarchy of themes) to find one. It an easy way to achieve just about any look you want for a theme.

==What's new in 2.0==

The theme system was completely redesigned in Moodle 2.0. Known issues have been addressed and new features have been added to meet community requests.

Unfortunately it was not possible to maintain backward compatibility, so all Moodle 1.x themes need to be recreated for Moodle 2.0.

Major changes include:
* Clearer and more consistent CSS classes and IDs throughout all pages in Moodle
* Introduction of layout files (templates) describing overall layout HTML for many different types of pages in Moodle.
* Introduction of renderers, which produce the smaller "parts" of a HTML page. Advanced themes can choose to override these too if they choose.
* Introduction of standard methods for adding Javascript to themes.
* Easier control over icons and images in Moodle.
* The old "standard" theme has been split into two themes:
**'''base''' - contains absolutely basic layout, and
**'''standard''' - which adds CSS to the base theme to make it look like the old standard theme.
* Performance tuning: In normal production mode CSS files are combined into a single optimised file, and both CSS and JavaScript files are minimised to ensure there are no wasted connections or traffic. Files are heavily cached, but also versioned, so that users never need to clear their caches.

==The structure of a theme==

Some important things to know when building good themes:

# '''config.php''' - this file is required in every theme. It defines configuration settings and definitions required to make the theme work in Moodle. These include theme, file, region, default region and options.
# '''Layouts and layout files''' - in config.php there is one definition for each page type (see [[#theme_layouts_table|Appendix A: Theme layouts]] for a list of over 12 types). Each page type definition tells Moodle which layout file will be used, what block regions this page type should display and so on. The layout file contains the HTML and the minimum PHP required to display basic structure of pages. (If you know Moodle 1.9, it's like a combination of header.html and footer.html).
# '''The base theme''' - is not intended to be used for production sites. It sets up the simplest possible generic layout and includes only CSS essential to that layout ''or'' to Moodle as a whole. It tries not to make any unnecessary rules and makes as few assumptions as possible. It's the perfect base on which to start designing a theme, as there are very few colours, borders, margins, and alignments to override. You can just start adding what you need.

===Files and folders===
A theme's files are placed in a folder with under moodle/theme folder and have subfolders. They are laid out like this:

{| class="nicetable"
|-
! Directory
! File
! Description
|-
|
| /config.php
| Contains all of the configuration and definitions for each theme
|-
|
| /lib.php
| Contains speciality classes and functions that are used by theme
|-
|
| /renderers.php
| Contains any custom renderers for the theme.
|-
|
| /settings.php
| Contains custom theme settings. These local settings are defined by the theme allowing the theme user to easily alter something about the way it looks or operates. (eg a background colour, or a header image)
|-
| /javascript/
|
| All specialty JavaScript files the theme requires should be located in here.
|-
| /lang/
|
| Any special language files the theme requires should be located in here.
|-
| /layout/
|
| Contains the layout files for the theme.
|-
| /pix/
|
| Contains any images the theme makes use of either in CSS or in the layout files.
|-
| /pix
| /favicon.ico
| The favicon to display for this theme.
|-
| /pix
| /screenshot.jpg
| A screenshot of the theme to be displayed in on the theme selection screen.
|-
| /style
|
| Default location for CSS files.
|-
|
|/*.css
|CSS files the theme requires
|}

There are also several other places that stylesheets can be included from (see the CSS how and why section below).

==Theme options==
All theme options are set within the config.php file for the theme. The settings that are most used are: parents, sheets, layouts, and javascripts. Have a look at the '''[[#theme_options_table|theme options table]]''' for a complete list of theme options which include lesser used specialised or advanced settings.

===Basic theme config example===
Lets have a look at a basic theme configuration file and the different bits that make it up:
<code php>
$THEME->name = 'newtheme';

$THEME->parents = array(
'base'
);

$THEME->sheets = array(
'admin',
'blocks',
'calendar',
'course',
'grade',
'message',
'question',
'user'
);

$THEME->layouts = array(
'base' => array(
'theme' => 'newtheme',
'file' => 'general.php',
'regions' => array(),
),
'standard' => array(
'theme' => 'newtheme',
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
)
//.......
);

$THEME->javascripts_footer = array(
'navigation'
);
</code>

===Basic theme example settings explained===
First up you will notice everything is added to $THEME. This is the theme's configuration object, it is created by Moodle using default settings and is then updated by whatever settings you add to it.

The first setting, $THEME->name is the theme's name. This should simply be whatever your theme's name is, most likely whatever you named your theme directory.

$THEME->parents defines the themes that the theme will extend. In this case it is extending only the base theme.

After this is the $THEME->sheets array containing the names of the CSS stylesheets to include for this theme. Note that it is just the name of the stylesheet and does not contain the directory or the file extension. Moodle assumes that the theme's stylesheets will be located in the styles directory of the theme and have .css as an extension.

Next we see the $THEME->layouts definition. In this example, two layouts have been defined to override the layouts from the base theme. For more information see the [[#Layouts|layouts]] section below.

The final setting is to include a JavaScript file, as $THEME->javascripts_footer. Much like stylesheets, you only need to provide the files name. Moodle will assume it is in your themes JavaScript directory and be a .js file.

'''''Note''''': When you first begin writing themes, make sure you take a look at the configuration files of the other themes that get shipped with Moodle. You will get a good picture of how everything works, and what is going on in a theme, simply by reading it and taking notice of what it is including or excluding.

==CSS==
===Locations of CSS files===
First lets look at where CSS can be included from within Moodle:
; \theme\themename\styles\*.css : This is the default location for all of the stylesheets that are used by a theme and the place which should be used by a theme designer.

New theme developers should note that the order in which CSS files are found and included creates a hierarchy. This order ensures that the rules, within a theme's style sheets, take precedence over identical rules in other files that may have been introduced before. This can both extend another files definitions (see parent array in the config file) and also ensures that the current theme's CSS rules/definitions have the last say.

There are other locations that can be used (although very rarely) to include CSS in a page. A developer of a php file can manually specify a stylesheet from anywhere within Moodle, like the database. Usually, if code is doing this, it is because there is a non-theme config or plugin setting that contains information requires special CSS information. As a theme designer you should be aware of, but not have to worry about, these locations of CSS files. Here are some examples:

; {pluginpath}\styles.css e.g. \block\blockname\styles.css or \mod\modname\styles.css : Every plugin can have its own styles.css file. This file should only contain the required CSS rules for the module and should not add anything to the look of the plugin such as colours, font sizes, or margins other than those that are truly required.<br />Theme specific styles for a plugin should be located within the themes styles directory.
; {pluginpath}\styles_themename.css : This should only ever be used by plugin developers. It allows them to write CSS that is designed for a specific theme without having to make changes to that theme. You will notice that this is never used within Moodle and is designed to be used only by contributed code.

As theme designers, we will only use the first method of introducing CSS: adding rules to a stylesheet file located in the themes styles directory.

===Moodle's core CSS organisation===
The next thing to look at is the organisation of CSS and rules within a theme. Although as a theme designer it is entirely up to you as to how you create and organise your CSS. Please note that within the themes provided in the standard install by Moodle there is a very clear organisation of CSS.

First is the pagelayout.css file. This contains the CSS required to give the layouts their look and feel. It doesn't contain any rules that affect the content generated by Moodle.

Next is the core.css file. If you open up core you will notice that it contains all manner of general (usually simple) rules that don't relate to a specific section of Moodle but to Moodle as a whole.

There can also be rules that relate to specific sections. However, this is done only when there are only a handful of rules for that section. These small clusters of rules are grouped together and separated by comments identifying for which section each relates.

Finally there are all the other CSS files, you will notice that there is a file for each section of Moodle that has a significant collection of rules.

:For those who are familiar with Moodle 1.9 theme's, this organisation will be a big change. In 1.9, CSS was organised by its nature (for example: colours, layout, other).

===How to write effective CSS rules within Moodle===
In Moodle 2.0, writing good CSS rules is an incredibly important.

Due to performance requirements and browser limitations, all of the CSS files are combined into a single CSS file that gets included every time. This means that rules need to be written in such a way as to minimise the chances of a collision leading to unwanted styles being applied. Whilst writing good CSS is something most designers strive for we have implemented several new body classes and put more emphasis on developers for using classes more appropriately.

====The body tag====
As of Moodle 2.0 the ID tag that gets applied to the body will always be a representation of the URI. For example if you are looking at a forum posting and the URI is '/mod/forum/view.php' then the body tags ID will be '#page-mod-forum-view'.

As well as the body's ID attribute the URI is also exploded to form several CSS classes that get added to the body tag, so in the above example '/mod/forum/view' you would end up with the following classes being added to the body tag '.path-mod', '.path-mod-forum'. Note that '.path-mod-forum-view' is not added as a class, this is intentionally left out to lessen confusion and duplication as rules can relate directly to the page by using the ID and do not require the final class.

The body ID and body classes described above will form the bread and butter for many of the CSS rules you will need to write for your theme, however there are also several other very handy classes that get added to the body tag that will be beneficial to you once you start your journey down the rabbit hole that is themeing. Some of the more interesting classes are listed below.

* If JavaScript is enabled then 'jsenabled' will be added as a class to the body tag allowing you to style based on JavaScript being enabled or not.
* Either 'dir-rtl' or 'dir-ltr' will be added to the body as a class depending on the direction of the language pack: rtl = right to left, ltr = left to right. This allows you to determine your text-alignment based on language if required.
* A class will be added to represent the language pack currently in use, by default en_utf8 is used by Moodle and will result in the class 'lang-en_utf8' being added to the body tag.
* The wwwroot for Moodle will also be converted to a class and added to the body tag allowing you to stylise your theme based on the URL through which it was reached. e.g. http://sam.moodle.local/moodle/ will become '.sam-moodle-local—moodle'
* If the current user is not logged then '.notloggedin' will be added to the body tag.

What does all of this look like in practise? Well using the above example /mod/forum/view.php you would get at least the following body tag:
<code html4strict><body id=”page-mod-forum-view” class=”path-mod path-mod-forum” /></code>

====Writing your rules====
The best use of body ids and classes and writing selectors will reduce problems.

There are many specific classes used within Moodle. We try to put them everywhere where anyone may want to apply their own styles. It is important to recognise that no one developer can be aware of the all of the class names that have been used all throughout Moodle, let alone within all of the different contributed bits and pieces available for Moodle. It is up to the theme developer to write good rules and minimise the chances of a collision between rules because in this case good CSS is FAR more effective.

When starting to write rules make sure that you have a good understanding of where you want those rules to be applied, it is a good idea to make the most of the body classes mentioned above.
If you want to write a rule for a specific page make use of the body tag's ID, e.g.:

<code css>#page-mod-forum-view .forumpost {border:1px solid orange;)</code>

If you want to write a rule that will be applied all throughout the forum.:

<code css>.path-mod-forum .forumpost {border:1px solid orange;}</code>

The other very important thing to take into consideration is the structure leading up to the tag you want to style. Browsers apply conflicting styles with priority on the more specific selectors. It can be very beneficial to keep this in mind and write full selectors that rely on the structure of the tags leading to the tag you wish to style.

By making use of body id's and classes and writing selectors to take into account the leading structure you can greatly minimise the chance of a collision both with Moodle now and in the future.

==Layouts==
All themes are required to define the layouts they wish to be responsible for as well as create; however, many layout files are required by those layouts. If the theme is overriding another theme then it is a case of deciding which layouts this new theme should override. If the theme is a completely fresh start then you will need to define a layout for each of the different possibilities. For both situations these layouts should be defined within config.php.

It is also important to note that a new theme that will base itself on another theme (overriding it) does not need to define any layouts or use any layout files if there are no changes that it wishes to make to the layouts of the existing theme. The standard theme in Moodle is a good example of this as it extends the base theme simply adding CSS to achieve its look and feel.

So layouts... as mentioned earlier layouts are defined in config.php within $THEME->layouts. The following is an example of one such layout definition:
<code php>
$THEME->layouts = array(
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'theme' => 'base',
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
)
)
</code>
The first thing Moodle looks at is the name of the layout, in this case it is `standard` (the array key in PHP), it then looks at the settings for the layout, this is the theme, file, regions, and default region. There are also a couple of other options that can be set by a layout.

; theme : is the theme the layout file exists in. That's right you can make use of layouts from other installed themes. ''Optional''
; file : is the name of the layout file this layout wants to use. ''Required''
; regions : is the different block regions (places you can put blocks) within the theme. ''Required''
; defaultregion : is the default location when adding new blocks. '''Required if regions is non-empty, otherwise optional'''
; options : an array of layout specific options described in detail below. '''Optional'''

The '''theme''' is optional. Normally the the layout file is looked for in the current theme, or, if it is not there, in the parent theme. However, you can use a layout file from any other theme by giving the theme name here.

You can define whatever regions you like. You just need to pick an name for each one. Most themes just use one or both of '''side_pre''' and '''side_post''', which is like 'left side' and 'right side', except in right to left languages, when they are reversed. If you say in config.php that your the layout provides regions called 'fred' and 'barney', then you must call $OUTPUT->blocks_for_region('fred') and $OUTPUT->blocks_for_region('barney') somewhere in the layout file.

The final setting '''options''' is a special case that only needs to be set if you want to make use of it. This setting allows the theme designer to specify special options that they would like to create that can be later accessed within the layout file. This allows the theme to make design decisions during the definition and react upon those decisions in what ever layout file is being used.

One such place this has been used is infact within the base theme. If you take a look first at theme/base/config.php you will notice that several layouts specify options '''nonavbar''' and '''nofooter''' which can both be set to either true or false. Then if we take a look at theme/base/layout/general.php you will spot lines like the following:
<code php>
<?php
$hasnavbar = (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar());
$hasfooter = (empty($PAGE->layout_options['nofooter']));
?>
............
<?php if ($hasnavbar) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
What you are seeing here is the use of those settings from the layout within the layout file. In this case it is being used to toggle the display of the navigation bar and page footer.

==Layout files==
A layout file is a file that contains the core HTML structure for a layout including the header, footer, content and block regions.
For those of you who are familiar with themes in Moodle 1.9 this is simply header.html and footer.html combined.
Of course it is not all HTML, there are bits of HTML and content that Moodle needs to put into the page, within each layout file this will be done by a couple of VERY simple PHP calls to get bits and pieces including content.

The following is a very simple layout file to illustrate the different bits that make it up:
<code php>
<?php echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
<body id="<?php p($PAGE->bodyid) ?>" class="<?php p($PAGE->bodyclasses) ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<table id="page">
<tr>
<td colspan="3">
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php echo $OUTPUT->login_info(); echo $PAGE->headingmenu; ?></div>
</td>
</tr>
<tr>
<td>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</td>
<td>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</td>
<td>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</td>
</tr>
<tr>
<td colspan="3">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</td>
</tr>
</table>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

Lets assume you know a enough HTML to understand the basic structure above, what you probably don't understand are the PHP calls so lets look at them.
<code php>
<?php echo $OUTPUT->doctype() ?>
</code>
This occurs at the VERY top of the page, it must be the first bit of output and is responsible for adding the (X)HTML document type definition to the page. This of course is determined by the settings of the site and is one of the things that the theme designer has no control over.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we have started writing the opening html tag and have asked Moodle to give us the HTML attributes that should be applied to it. This again is determined by several settings within the actual HTML install.

<code php>
<?php echo $PAGE->title ?>
</code>
This gets us the title for the page.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
This very important call gets us the standard head HTML that needs to be within the HEAD tag of the page. This is where CSS and JavaScript requirements for the top of the page will be output as well as any special script or style tags.

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
</code>
Much like the html tag above we have started writing the body tag and have asked for Moodle to get us the desired ID and classes that should be applied to it.

<code php>
<h1 class="headermain"><?php echo $PAGE->heading; ?></h1>
<div class="headermenu"><?php echo $OUTPUT->login_info(); echo $PAGE->headingmenu; ?></div>
</code>
Here we are creating the header for the page. In this case we want the heading for the page, we want to display the login information which will be the current users username or a link to log in if they are not logged in, and we want the heading menu if there is one.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
Here we get the HTML to display the blocks that have been added to the page. In this case we have asked for all blocks that have been added to the area labelled ''side-pre''.

<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This is one of the most important calls within the file, it determines where the actual content for the page gets inserted.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we get the HTML to display the blocks that have been added to the page. In this case we have asked for all blocks that have been added to the area labelled ''side-post''.

<code php>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</code>
This final bit of code gets the content for the footer of the page. It gets the login information which is the same as in the header, a home link, and the standard footer HTML which like the standard head HTML contains all of the script and style tags required by the page and requested to go in the footer.

'''''Note''''': Within Moodle 2.0 most of the JavaScript for the page will be included in the footer. This greatly helps reduce the loading time of the page.

When writing layout files think about the different layouts and how the HTML that each makes use of will differ. You will most likely find you do not need a different layout file for each layout, most likely you will be able to reuse the layout files you create across several layouts. You can of course make use of layout options as well to further reduce the number of layout files you need to produce.

Of course as mentioned above if you are customising an existing theme then you may not need to create any layouts or layout files at all.

'''$OUTPUT''' is an instance of the '''core_renderer''' class which is defined in lib/outputrenderers.php. Each method is clearly documented there, along with which is appropriate for use within the layout files.

'''$PAGE''' is an instance of the '''moodle_page''' class defined in lib/pagelib.php. Most of the things you will want to use are the properties that are all documented at the top of the file. If you are not familiar with PHP properties, you access them like $PAGE->activityname, just like fields of an ordinary PHP object. (However, behind the scenes, some magic is going on, and the value you get is produced by calling a function. Also, you cannot change these values, they are read-only. However, you don't need to understand all that if you are just using these properties in your theme.)

==Language File==

You need to create a language file for your theme with a few standard strings in it. At a minimum create a file called lang/en.theme_themename.php in your theme folder. For example, the 'standard' theme has a language file called lang/en/theme_standard.php.

You '''must''' define the following lines in your file (example is from standard theme, adapt as required):

<code php>
$string['pluginname'] = 'Standard';
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
$string['choosereadme'] = 'This theme is a very basic white theme, with a minimum amount of
CSS added to the base theme to make it actually usable.';
</code>

Without the above you will get notices for the missing strings.

==Making use of images==
Right at the start when listing the features of the new themes system one of the features mentioned was the ability to override any of the standard images within Moodle from within your theme. At this point we will look at both how to make use of your own images within your theme, and secondly how to override the images being used by Moodle.
So first up a bit about images within Moodle,

# Images you want to use within your theme '''need''' to be located within your theme's pix directory.
# You can use sub directories within the pix directory of your theme.
# Images used by Moodle's core are located within the pix directory of Moodle.
# Modules, blocks and other plugins should also store there images within a pix directory.

So making use of your own images first up. Lets assume you have added two image files to the pix directory of your theme.

* /theme/yourthemename/pix/imageone.jpg
* /theme/yourthemename/pix/subdir/imagetwo.png

Notice that one image is a JPEG image, and the second is a PNG. Also the second image is in a subdirectory.

The following code snippet illustrates how to make use of your images within HTML, such as if you wanted to use them within a layout file.
<code php>
<img src="<?php echo $OUTPUT->pix_url('imageone', 'theme');?>" alt="" />
<img src="<?php echo $OUTPUT->pix_url('subdir/imagetwo', 'theme');?>" alt="" />
</code>

'''DO NOT''' include the image file extension. Moodle will work it out automatically and it will not work if you do include it.

In this case rather than writing out the URL to the image we use a method of Moodle's output library. Its not too important how that functions works but it is important that we use it as it is what allows images within Moodle to be over-rideable.

The following is how you would use the images from within CSS as background images.
<code css>
.divone {background-image:url([[pix:theme|imageone]]);}
.divtwo {background-image:url([[pix:theme|subdir/imagetwo]]);}
</code>
If this case we have to use some special notations that Moodle looks for. Whenever Moodle hands out a CSS file it first searches for all ''[[something]]'' tags and replaces them with what is required.

The final thing to notice with both of the cases above is that at no point do we include the images file extension.
The reason for this leads us into the next topic, how to override images.

From within a theme you can VERY easily override any standard image within Moodle by simply adding the replacement image to the theme's pix directory in the same sub directory structure as it is in Moodle.
So for instance we wanted to override the following two images:
# /pix/moodlelogo.gif
# /pix/i/user.gif
We would simply need to add our replacement images to the theme in the following locations
# /theme/themename/pix/moodlelogo.gif
# /theme/themename/pix/i/user.gif
How easy is that!

Now the other very cool thing to mention is that Moodle looks for not just replacements of the same image type (jpg, gif, etc...) but also replacements in any image format. This is why above when working with our images we never specified the images file extension.
This means that the following would also work:
# /theme/themename/pix/moodlelogo.png
# /theme/themename/pix/i/user.bmp

For a more detailed description of how this all works see the page on [[Development:Themes_2.0_How_to_use_images_within_your_theme|using images within your theme]]

==Unobvious Things==
===Getting Your Theme to Appear Correctly in Theme Selector===
If you follow the examples on this page to the letter, when you go to the Theme Selector page you may be discouraged to find that your theme does not appear like the other themes do. In fact, instead of your theme's name, you will see something along the lines of <nowiki>[[pluginname]]</nowiki>.

To correct this, you must add the /lang/en/theme_THEMENAME.php file, where THEMENAME is the name of the theme folder. Inside that file, add the string "$string['pluginname'] = 'THEMENAME'; ". Make THEMENAME the name of your theme, however you want it displayed in the Theme selector.

The screenshot for the theme should be about 500x400 px.

===Required theme divs===

Some parts of Moodle may rely on particular divs, for example the div with id 'page-header'.

Consequently all themes must include at least the divs (with the same ids) that are present in the 'base' theme.

Missing out these elements may result in unexpected behaviour within specific modules or other plugins.

==Appendix A==
===Theme options as of April 28th, 2010===
{| class="nicetable" id="theme_options_table"
|-
! Setting
! Effect
|-
| $THEME->'''csspostprocess'''
| Allows the user to provide the name of a function that all CSS should be passed to before being delivered.
|-
| $THEME->'''editor_sheets'''
| An array of stylesheets to include within the body of the editor.
|-
| $THEME->'''enable_dock'''
| If set to true the side dock is enabled for blocks
|-
| $THEME->'''hidefromselector'''
| Used to hide a theme from the theme selector (unless theme designer mode is on). Accepts true or false.
|-
| $THEME->'''filter_mediaplugin_colors'''
| Used to control the colours used in the small media player for the filters
|-
| $THEME->'''javascripts'''
| An array containing the names of JavaScript files located in /javascript/ to include in the theme. (gets included in the head)
|-
| $THEME->'''javascripts_footer'''
| As above but will be included in the page footer.
|-
| $THEME->'''larrow'''
| Overrides the left arrow image used throughout Moodle
|-
| $THEME->'''layouts'''
| An array setting the layouts for the theme
|-
| $THEME->'''name'''
| Name of the theme. Most likely the name of the directory in which this file resides.
|-
| $THEME->'''parents'''
| An array of themes to inherit from
|-
| $THEME->'''parents_exclude_javascripts'''
| An array of JavaScript files NOT to inherit from the themes parents
|-
| $THEME->'''parents_exclude_sheets'''
| An array of stylesheets not to inherit from the themes parents
|-
| $THEME->'''plugins_exclude_sheets'''
| An array of plugin sheets to ignore and not include.
|-
| $THEME->'''rarrow'''
| Overrides the right arrow image used throughout Moodle
|-
| $THEME->'''renderfactory'''
| Sets a custom render factory to use with the theme, used when working with custom renderers.
|-
| $THEME->'''resource_mp3player_colors'''
| Controls the colours for the MP3 player
|-
| $THEME->'''sheets'''
| An array of stylesheets to include for this theme. Should be located in the theme's style directory.
|}
===The different layouts as of August 17th, 2010===
{| class="nicetable" id="theme_layouts_table"
|-
! Layout
! Purpose
|-
| base
| Most backwards compatible layout without the blocks - this is the layout used by default.
|-
| standard
| Standard layout with blocks, this is recommended for most pages with general information.
|-
| course
| Main course page.
|-
| coursecategory
| Use for browsing through course categories.
|-
| incourse
| Default layout while browsing a course, typical for modules.
|-
| frontpage
| The site home page.
|-
| admin
| Administration pages and scripts.
|-
| mydashboard
| My dashboard page.
|-
| mypublic
| My public page.
|-
| login
| The login page.
|-
| popup
| Pages that appear in pop-up windows - no navigation, no blocks, no header.
|-
| frametop
| Used for legacy frame layouts only. No blocks and minimal footer.
|-
| embedded
| Embeded pages, like iframe/object embedded in moodleform - it needs as much space as possible
|-
| maintenance
| Used during upgrade and install. 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.
|-
| print
| Used when the page is being displayed specifically for printing.
|}

==See also==

* [[Development:Themes 2.0 creating your first theme]] - A quick step by step guide to creating your first theme.
* [[Development:Themes 2.0 overriding a renderer]] - A tutorial on creating a custom renderer and changing the HTML Moodle produces.
* [[Development:Themes 2.0 How to use images within your theme]] - Explains how to use and override images within your theme.
* [[Development:Themes 2.0 adding a settings page]] - Looks at how to add a setting page making your theme easily customisable.
* [[Development:Themes 2.0 extending the custom menu]] - Customising the custom menu.
* [[Development:Themes 2.0 adding courses and categories to the custom menu]] - Extending the custom menu further adding all categories + courses
* [[Development:Themes 2.0 how to make the dock horizontal]] - Modifying the dock to make it horizontal.
* [[Development:Themes 2.0 adding upgrade code]]
* [[Development:Styling and customising the dock]] - How to style and customise the dock.
* [[Development:Theme changes in 2.0]]
* [[Development:Using jQuery with Moodle 2.0]]
* [[Development:Themes 2.0 how to clone a Moodle 2.0 theme]]
* [http://www.youtube.com/watch?v=OvaU54uh-qA New themes in Moodle 2.0 video]

[[de:Designs 2.0]]
[[es:Temas 2.0]]

Administrator documentation

2011-05-26T09:06:17Z

Howardsmiller: Undo revision 83864 by Howardsmiller (talk)

The purpose of this page is to list useful links by general topics for administrators of a Moodle site.
__TOC__

== Installation & Upgrading ==

*[[Installation Quickstart]] for an overview of the installation steps
*[[Installing Moodle]] for detailed installation instructions
*[[Installation FAQ]]
*[[Installing AMP|Options for installing Apache, MySQL and PHP]]
*[[Upgrading|Upgrading Moodle]]
*[[Installing contributed modules or plugins]]

== System-specific Instructions & Packages ==

===Unix/Linux-based===
* [[SUSE Linux Server 10|Automated Installation Guide for SUSE Linux Enterprise Server 10]] operating system
* [[RedHat Linux installation|Step-by-step Installation Guide for RedHat]] operating system
* [[Debian GNU/Linux installation|Step-by-step Installation Guide for Debian GNU/Linux]] operating system
* [[Step-by-step Installation Guide for Ubuntu]]
* [[Manual installation of Moodle 2.0 on Mythbuntu using Git|Manual installation of Moodle 2.0 on Mythbuntu (and Ubuntu 10.10, 11.04) using Git]]
* [[Manual_installation_on_Ubuntu|Manual Installation on Ubuntu]]
* [[Step-by-step Install Guide for Zenwalk-5.0|Step-by-step Installation Guide for Zenwalk-5.0]]
* [[OLPC XS installation|Step-by-step Installation Guide for the One Laptop per Child XS Server (Beta)]]
* [[Step-by-step Install Guide for Solaris 10 with Oracle 10|Step-by-step Installation Guide for Solaris 10 with Oracle 10]]
* [[Installation Guide for Installing on Amazon EC2]]

===Windows===
* [[Windows installation|Windows installations with instructions for Windows NT/2000/2003 servers]]
* [[Windows installation using XAMPP|Windows installation using XAMPP: Apache, MySQL and PHP]]
* [[Development:Windows_Installer_anywhere|MoodleAnywhere]] another Windows installation package
* [[Installing Moodle on Windows Vista]] - how to
* [http://www.bfcnetworks.com/whitepapers/installing-moodle-on-windows-server-iis-sql/ Installing Moodle on Windows Server 2008 x86]
* [http://www.bfcnetworks.com/whitepapers/installing-moodle-on-windows-server-2008-r2-x64-sql-iis/ Installing Moodle on Windows Server 2008 R2]
* [http://www.bfcnetworks.com/whitepapers/implementing-moodle-on-a-windows-high-availability-environment// Implementing Moodle on a Windows High Availability Environment] Implementing Moodle 1.9 on 2 Microsoft Load Balanced Web Front End Server and a Microsoft SQL Server 2008 R2 Cluster environment

Moodle 2
* [http://www.bfcnetworks.com/whitepapers/installing-moodle-2-on-windows-server-mysql-php-and-iis7/ Installing Moodle 2 on Windows Server, MySQL, PHP and IIS7]
* [http://www.bfcnetworks.com/whitepapers/installing-moodle-2-on-windows-server-2008-r2-x64-sql-iis/ Installing Moodle 2 on Windows Server, Microsoft SQL Server, PHP and IIS7]

===Mac===
* [[Step by Step Installation on a Mac OS X Server|Step by step Installation on a Mac OS X Server 10.5/10.6]]
* [[Complete Install Packages for Mac OS X | Complete Install Packages for Mac OS X Clients 10.4/10.5/10.6]]
* [[Step-by-step Guide for Installing Moodle on Mac OS X 10.4 Client|Step by Step Installation on a Mac OS X 10.4 Client using the internal web server]]

===Web Hosts===
* [[1and1_MySQL_installation | Installation on '''1and1''' web hosting]]
* [[powweb_MySQL_installation | Step-by-step Installation on '''Powweb''' web hosting]]
* [[Step-by-step Installation using the old version of CPanel]]
* [[Step-by-step Installation using the new version of CPanel]]

===Appliances===
Some users may prefer to skip manual installation by using a pre-integrated [[Moodle appliance]].

===Database===
* [[Installing Oracle for PHP]]
* [[Installing MSSQL for PHP]]
* [[Installing Postgres for PHP]]

===Plugins===
* [[Installing contributed modules or plugins]]

==Security, Performance and Roles==

*[[Security]] contains important security procedures for a production site
*[[Performance]] for ideas on improving the speed of your installation
*[[Manage roles]] For Moodle 1.7 and later.
*[[Reducing spam in Moodle]]
*[[suhosin]] is an advanced protection system for PHP installation. It was designed to protect servers and users from known and unknown flaws in PHP applications and the PHP core.
*[[nagios]] Open source software to monitor servers

== FAQs ==

*[[Installation FAQ]]
*[[Beginning Administration FAQ]]
*[[Administration FAQ]]
*[[Performance FAQ]]
*[[Backup and restore FAQ]]
*[[Errors FAQ]]
*[[:Category:FAQ|List of FAQs]]

== Configuration Settings ==
=== Site administration setting===
[[Site administration block]] contains most site configuration settings including:
*[[Front Page settings]]- initial or home page of a Moodle site
*[[Themes]] - user interface packages of XHTML and CSS controls
*[[Language]] - default and additional language packs
*[[Activity modules administration]]
*[[Blocks administration]]
*[[Filters]] - Text and Multimedea plugins
*[[Backup settings]]
*[[HTML editor settings]]
*[[Calendar settings]]
*[[Maintenance mode]]
*[[Notification page]] used to update versions
*[[Settings block]] Moodle 2.0 site settings location

===Other settings===
*[[Course settings]] for course home page configuration
**Each type of [[Activities|activity]], [[resource]] and [[:Category:Block|block]] has their own settings
*Older versions settings
**[[Site settings]] pre 1.7
**[[Variables]] pre 1.6
**[[Location of admin settings in 1.7|Comparison between configuration settings in Moodle 1.6 & 1.7]]

==User Management==

*[[Authentication]] of user on a site
*[[Add new user|Add a new user]] - on a site
*[[Upload users]] - from a file to a site, and into existing course and group, some existing user global updates
*[[User_profile_fields]]
*[[Enrolment plugins]]
**[[Flat file]] - enrol existing users in a course
*[[Roles and capabilities|Assigning user a role]] - typical assignments include:
**[[Students|Enrol students in a course]]
**[[Unenrolment]] Student
**[[Courses (administrator)|Assign teachers]] - to a course
**[[Assign creators|Assign course creators]] - in a site
**[[Assign administrators]] - in a site

==Other==

*[[Courses (administrator)|Courses]] and [[Course formats|course formats]]
*[[Reports (administrator)]] and [[Logs]]
*[[Site files]]
*[[Moodle database|Moodle site database]]
*[[Environment]]
*[[MNet|Moodle Network]] and Moodle [[Community hub]]
*[[Streaming Media]]
*[[Case studies (administrator)]]
*[[Anti-virus]]
*[[System Monitoring and Server Statistic Software]]
*[[Integrate Moodle, LDAP and SIMS.net]]
*[[How to rebuild context paths]]
*[[Hacking the Moodle 2.0 database transfer script to convert a Moodle 1.9 site]]
*[[Category:ProxyProblems]]

==See also==

*[[:Category:Administrator | Index of all Administrator-related pages]]
*[[Integrations]]
*[[CVS for Administrators]]
*[[Email processing]]
*[[Search engine optimization]]
*[[Messaging]]
*[[Migration]]
*[[Metacourses]]
*[[Block layout]]
*[[Customizing Moodle]]
*[[Administrator do's and don'ts]]
*[[Using Moodle book]] Chapter 16: Moodle Administration
*[[Administration hacks]]
*[[Git]] Version control, upgrading

[[Category: Administrator]]
[[cs:Rukověť správce]]
[[es:Documentación para Administradores]]
[[eu:Kudeatzaileentzako dokumentazioa]]
[[fr:Documentation administrateur]]
[[ja:管理者ドキュメント]]
[[ko:관리자 문서]]
[[nl:Documentatie voor beheerders]]
[[pt:Documentação para administradores]]
[[ru:Администраторам]]
[[sk:Dokumentácia pre správcov]]
[[zh:管理员文档]]
[[pl:Administrator documentation]]
[[fi:Ylläpitäjän opas]]
[[de:Dokumentation für Administratoren]]

Administrator documentation

2011-05-26T09:04:27Z

Howardsmiller: /* Unix/Linux-based */

The purpose of this page is to list useful links by general topics for administrators of a Moodle site.
__TOC__

== Installation & Upgrading ==

*[[Installation Quickstart]] for an overview of the installation steps
*[[Installing Moodle]] for detailed installation instructions
*[[Installation FAQ]]
*[[Installing AMP|Options for installing Apache, MySQL and PHP]]
*[[Upgrading|Upgrading Moodle]]
*[[Installing contributed modules or plugins]]

== System-specific Instructions & Packages ==

===Unix/Linux-based===
* [[SUSE Linux Server 10|Automated Installation Guide for SUSE Linux Enterprise Server 10]] operating system
* [[RedHat Linux installation|Step-by-step Installation Guide for RedHat]] operating system
* [[Debian GNU/Linux installation|Step-by-step Installation Guide for Debian GNU/Linux]] operating system
* [[Step-by-step Installation Guide for Ubuntu]]
* [[Manual installation of Moodle 2.0 on Mythbuntu (and Ubuntu 10.10, 11.04) using Git]]
* [[Manual_installation_on_Ubuntu|Manual Installation on Ubuntu]]
* [[Step-by-step Install Guide for Zenwalk-5.0|Step-by-step Installation Guide for Zenwalk-5.0]]
* [[OLPC XS installation|Step-by-step Installation Guide for the One Laptop per Child XS Server (Beta)]]
* [[Step-by-step Install Guide for Solaris 10 with Oracle 10|Step-by-step Installation Guide for Solaris 10 with Oracle 10]]
* [[Installation Guide for Installing on Amazon EC2]]

===Windows===
* [[Windows installation|Windows installations with instructions for Windows NT/2000/2003 servers]]
* [[Windows installation using XAMPP|Windows installation using XAMPP: Apache, MySQL and PHP]]
* [[Development:Windows_Installer_anywhere|MoodleAnywhere]] another Windows installation package
* [[Installing Moodle on Windows Vista]] - how to
* [http://www.bfcnetworks.com/whitepapers/installing-moodle-on-windows-server-iis-sql/ Installing Moodle on Windows Server 2008 x86]
* [http://www.bfcnetworks.com/whitepapers/installing-moodle-on-windows-server-2008-r2-x64-sql-iis/ Installing Moodle on Windows Server 2008 R2]
* [http://www.bfcnetworks.com/whitepapers/implementing-moodle-on-a-windows-high-availability-environment// Implementing Moodle on a Windows High Availability Environment] Implementing Moodle 1.9 on 2 Microsoft Load Balanced Web Front End Server and a Microsoft SQL Server 2008 R2 Cluster environment

Moodle 2
* [http://www.bfcnetworks.com/whitepapers/installing-moodle-2-on-windows-server-mysql-php-and-iis7/ Installing Moodle 2 on Windows Server, MySQL, PHP and IIS7]
* [http://www.bfcnetworks.com/whitepapers/installing-moodle-2-on-windows-server-2008-r2-x64-sql-iis/ Installing Moodle 2 on Windows Server, Microsoft SQL Server, PHP and IIS7]

===Mac===
* [[Step by Step Installation on a Mac OS X Server|Step by step Installation on a Mac OS X Server 10.5/10.6]]
* [[Complete Install Packages for Mac OS X | Complete Install Packages for Mac OS X Clients 10.4/10.5/10.6]]
* [[Step-by-step Guide for Installing Moodle on Mac OS X 10.4 Client|Step by Step Installation on a Mac OS X 10.4 Client using the internal web server]]

===Web Hosts===
* [[1and1_MySQL_installation | Installation on '''1and1''' web hosting]]
* [[powweb_MySQL_installation | Step-by-step Installation on '''Powweb''' web hosting]]
* [[Step-by-step Installation using the old version of CPanel]]
* [[Step-by-step Installation using the new version of CPanel]]

===Appliances===
Some users may prefer to skip manual installation by using a pre-integrated [[Moodle appliance]].

===Database===
* [[Installing Oracle for PHP]]
* [[Installing MSSQL for PHP]]
* [[Installing Postgres for PHP]]

===Plugins===
* [[Installing contributed modules or plugins]]

==Security, Performance and Roles==

*[[Security]] contains important security procedures for a production site
*[[Performance]] for ideas on improving the speed of your installation
*[[Manage roles]] For Moodle 1.7 and later.
*[[Reducing spam in Moodle]]
*[[suhosin]] is an advanced protection system for PHP installation. It was designed to protect servers and users from known and unknown flaws in PHP applications and the PHP core.
*[[nagios]] Open source software to monitor servers

== FAQs ==

*[[Installation FAQ]]
*[[Beginning Administration FAQ]]
*[[Administration FAQ]]
*[[Performance FAQ]]
*[[Backup and restore FAQ]]
*[[Errors FAQ]]
*[[:Category:FAQ|List of FAQs]]

== Configuration Settings ==
=== Site administration setting===
[[Site administration block]] contains most site configuration settings including:
*[[Front Page settings]]- initial or home page of a Moodle site
*[[Themes]] - user interface packages of XHTML and CSS controls
*[[Language]] - default and additional language packs
*[[Activity modules administration]]
*[[Blocks administration]]
*[[Filters]] - Text and Multimedea plugins
*[[Backup settings]]
*[[HTML editor settings]]
*[[Calendar settings]]
*[[Maintenance mode]]
*[[Notification page]] used to update versions
*[[Settings block]] Moodle 2.0 site settings location

===Other settings===
*[[Course settings]] for course home page configuration
**Each type of [[Activities|activity]], [[resource]] and [[:Category:Block|block]] has their own settings
*Older versions settings
**[[Site settings]] pre 1.7
**[[Variables]] pre 1.6
**[[Location of admin settings in 1.7|Comparison between configuration settings in Moodle 1.6 & 1.7]]

==User Management==

*[[Authentication]] of user on a site
*[[Add new user|Add a new user]] - on a site
*[[Upload users]] - from a file to a site, and into existing course and group, some existing user global updates
*[[User_profile_fields]]
*[[Enrolment plugins]]
**[[Flat file]] - enrol existing users in a course
*[[Roles and capabilities|Assigning user a role]] - typical assignments include:
**[[Students|Enrol students in a course]]
**[[Unenrolment]] Student
**[[Courses (administrator)|Assign teachers]] - to a course
**[[Assign creators|Assign course creators]] - in a site
**[[Assign administrators]] - in a site

==Other==

*[[Courses (administrator)|Courses]] and [[Course formats|course formats]]
*[[Reports (administrator)]] and [[Logs]]
*[[Site files]]
*[[Moodle database|Moodle site database]]
*[[Environment]]
*[[MNet|Moodle Network]] and Moodle [[Community hub]]
*[[Streaming Media]]
*[[Case studies (administrator)]]
*[[Anti-virus]]
*[[System Monitoring and Server Statistic Software]]
*[[Integrate Moodle, LDAP and SIMS.net]]
*[[How to rebuild context paths]]
*[[Hacking the Moodle 2.0 database transfer script to convert a Moodle 1.9 site]]
*[[Category:ProxyProblems]]

==See also==

*[[:Category:Administrator | Index of all Administrator-related pages]]
*[[Integrations]]
*[[CVS for Administrators]]
*[[Email processing]]
*[[Search engine optimization]]
*[[Messaging]]
*[[Migration]]
*[[Metacourses]]
*[[Block layout]]
*[[Customizing Moodle]]
*[[Administrator do's and don'ts]]
*[[Using Moodle book]] Chapter 16: Moodle Administration
*[[Administration hacks]]
*[[Git]] Version control, upgrading

[[Category: Administrator]]
[[cs:Rukověť správce]]
[[es:Documentación para Administradores]]
[[eu:Kudeatzaileentzako dokumentazioa]]
[[fr:Documentation administrateur]]
[[ja:管理者ドキュメント]]
[[ko:관리자 문서]]
[[nl:Documentatie voor beheerders]]
[[pt:Documentação para administradores]]
[[ru:Администраторам]]
[[sk:Dokumentácia pre správcov]]
[[zh:管理员文档]]
[[pl:Administrator documentation]]
[[fi:Ylläpitäjän opas]]
[[de:Dokumentation für Administratoren]]

HTML editor FAQ

2011-05-12T18:32:09Z

Howardsmiller: /* The HTML Editor does not appear */

Be sure to see the [[HTML editor]] page for more information.

==I can't find the option to do......==

Click the icon at the far right of the bottom row (two boxes with an arrow). It will say "Enlarge Editor" when you hover over it. The editor will now appear in a pop-up with the full range of options available (e.g. tables).

==The HTML Editor does not appear==

Check the following points and/or discussions (in no particular order);

* Prior to 1.9.11 HTMLArea only supported Firefox and Internet Explorer. Thereafter Chrome and Safari (but not in mobile devices) are also supported.
* GoDaddy http://moodle.org/mod/forum/discuss.php?d=117556
* Analytics code or advertisement scripts http://moodle.org/mod/forum/discuss.php?d=117034
* Hacked site / injected code http://moodle.org/mod/forum/discuss.php?d=116374
* Editor can be disabled from Administration > Appearance > HTML editor > Use HTML editor or
* Editor can be disabled from user profile (When editing text > Use standard web forms)
* Settings of browser (javascript may be disabled)
* Some custom plugin may break source code
* Check the config.php file - remove the closing '?>' at the end (it doesn't need it). Make sure you haven't used a broken editor (anything Microsoft wrote, typically) that may have corrupted the file.

==How can I enable a spell-check?==

If you want the HTML editor to have a spell-check button, you need to install aspell 0.50 or later on your server, and enter the correct path to access the aspell binary in ''Administration > Server > [[System paths]]''.

==How we can disable the spell check button for specific instances in a quiz?==
The spell check is very handy for most circumstances but a quiz where you are looking at spelling and punctuation in student responses kind of defeats the purpose of the question. You can use the theme CSS files to disable the button on a specific question type. Try:

.essay div[title='Spell-check'] {
display:none;
}

The spell check button should be displayed everywhere '''except''' on the essay question type response box.

Suggested by Joshua Westerway.

==What is new with the HTML editor in Moodle 2.0?==

See [[HTML editor 2.0]].

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?f=224 HTML editor forum]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=103418 Students can't upload files using HTML editor] forum discussion

[[Category:HTML editor]]
[[Category:FAQ]]

HTML editor FAQ

2011-05-12T14:32:20Z

Howardsmiller: /* The HTML Editor does not appear */

Be sure to see the [[HTML editor]] page for more information.

==I can't find the option to do......==

Click the icon at the far right of the bottom row (two boxes with an arrow). It will say "Enlarge Editor" when you hover over it. The editor will now appear in a pop-up with the full range of options available (e.g. tables).

==The HTML Editor does not appear==

Check the following points and/or discussions (in no particular order);

* Prior to 1.9.11 HTMLArea only supported Firefox and Internet Explorer. Thereafter Chrome and Safari (but not in mobile devices) are also supported.
* GoDaddy http://moodle.org/mod/forum/discuss.php?d=117556
* Analytics code or advertisement scripts http://moodle.org/mod/forum/discuss.php?d=117034
* Hacked site / injected code http://moodle.org/mod/forum/discuss.php?d=116374
* Editor can be disabled from Administration > Appearance > HTML editor > Use HTML editor or
* Editor can be disabled from user profile (When editing text > Use standard web forms)
* Settings of browser (javascript may be disabled)
* Some custom plugin may break source code

==How can I enable a spell-check?==

If you want the HTML editor to have a spell-check button, you need to install aspell 0.50 or later on your server, and enter the correct path to access the aspell binary in ''Administration > Server > [[System paths]]''.

==How we can disable the spell check button for specific instances in a quiz?==
The spell check is very handy for most circumstances but a quiz where you are looking at spelling and punctuation in student responses kind of defeats the purpose of the question. You can use the theme CSS files to disable the button on a specific question type. Try:

.essay div[title='Spell-check'] {
display:none;
}

The spell check button should be displayed everywhere '''except''' on the essay question type response box.

Suggested by Joshua Westerway.

==What is new with the HTML editor in Moodle 2.0?==

See [[HTML editor 2.0]].

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?f=224 HTML editor forum]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=103418 Students can't upload files using HTML editor] forum discussion

[[Category:HTML editor]]
[[Category:FAQ]]

Cookie Sessions

2011-05-04T06:43:55Z

Howardsmiller: spelling

'''Troubleshooting'''

Some users get the following error when trying to login to their moodle: <code>A server error that affects your login session was detected. Please login again or restart your browser</code>
or even: <code>Your session has timed out. Please login again</code>

'''Solution'''

* check and fix your permissions in moodledata/session -- set it to 0777
* check config.php, it should NOT has any spaces/new lines at the end of code. Repeat this on all moodle php files you lately changed, such as course/lib.php
* In admin > server > session handling > "Cookie Prefix" put something in the Cookie prefix field that is different for each of your moodle sites, and it should improve the issue with multiple sites on the same url.
* test your server's sessions by running session test on http://yourserver/moodle/lib/session-test.php
* check your phpinfo(); if it session handeling is configured correctly or not.

[[Category:Developer]]
[[Category:Administrator]]
[[Category:Cookies]]

Development:Using the File API in Moodle forms

2011-04-22T08:14:15Z

Howardsmiller: /* Add file manager element */

{{Moodle 2.0}}

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

==Overview==

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

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

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

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

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

==Form elements==

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

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

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

===filepicker===

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

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

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

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

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

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

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

=== filemanager ===

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

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

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

Here are the fields for filemanager:

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

The options array can contain:

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

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

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

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

$mform->set_data($entry);

</code>

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

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

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

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

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

====Low level use====

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

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

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES));
</code>
The editor element can take following options: maxfiles, maxbytes, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

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

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

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

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

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

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

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

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

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

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'mod_glossary', 'entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'component', 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[Development:File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

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

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
$context->id, 'mod_mymodule', 'proper_file_area', $itemid);
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; $context->id, 'mod_mymodule', 'proper_file_area', $itemid : uniquely identifies the file area, as before.

=== Implement file serving access control ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== See also ==

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

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

Development:Using the File API in Moodle forms

2011-04-22T08:13:24Z

Howardsmiller: Correcting file location

{{Moodle 2.0}}

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

==Overview==

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

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

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

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

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

==Form elements==

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

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

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

===filepicker===

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

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

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

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

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

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

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

=== filemanager ===

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

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

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

Here are the fields for filemanager:

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

The options array can contain:

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

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

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

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

$mform->set_data($entry);

</code>

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

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

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

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

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

====Low level use====

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

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

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES));
</code>
The editor element can take following options: maxfiles, maxbytes, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

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

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

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

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

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

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

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

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

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

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'mod_glossary', 'entry', $entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'component', 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[Development:File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

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

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
$context->id, 'mod_mymodule', 'proper_file_area', $itemid);
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; $context->id, 'mod_mymodule', 'proper_file_area', $itemid : uniquely identifies the file area, as before.

=== Implement file serving access control ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== See also ==

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

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

Errors FAQ

2011-04-12T08:25:46Z

Howardsmiller: /* Fatal error allowed memory size exhausted. How do I increase my php memory limit? */

==Error: database connection failed==

If you get errors like "database connection failed" or "could not connect to the database you specified", here are some possible reasons and some possible solutions.

* Your '''database server''' isn't installed or running. To check this for MySQL try typing the following command line
$telnet database_host_name 3306
:You should get a cryptic response which includes the version number of the MySQL server.
* If you are attempting to run '''two instances of Moodle on different ports''', use the ip address of the host (not localhost) in the $CFG->dbhost setting, e.g. $CFG->dbhost = 127.0.0.1:3308.
* You don't have the '''PHP mysql or postgresql extensions''' installed (please refer to FAQ re. whether PHP is installed).
* You haven't created a '''Moodle database and assigned a user''' with the correct privileges to access it.
* The '''Moodle database settings''' are incorrect. The database name, database user or database user password in your Moodle configuration file ''config.php'' are incorrect. Use phpMyAdmin to set up and check your MySQL installation.
* Check that there are '''no apostrophes or non-alphabetic letters''' in your MySQL username or password.
* You are using MySQL version 4.1 or higher but the PHP MySQL extension is pre-4.1 (check in your phpinfo output). In this case the '''default password hashing algorithm''' is incompatible with that available in the PHP mysql extension versions 4.x.x. Use these MySQL commands to change the passwords to the old format:

mysql>SET PASSWORD FOR 'root'@'localhost' = OLD_PASSWORD('password');
mysql>SET PASSWORD FOR 'moodleuser'@'localhost' = OLD_PASSWORD('password');

:Also, consider upgrading your PHP MySQL extension. See [http://dev.mysql.com/doc/mysql/en/old-client.html this MySQL document] for further information on how to deal with this problem.
* You are using Fedora core 3 or some other Linux system with '''SELinux installed''' and enabled. See the following URL for information on how to disable SELinux: http://fedora.redhat.com/projects/selinux/ If you don't want to disable SELinux, you have to allow httpd process to create network connections:

setsebool httpd_can_network_connect true

* Mac OSX users -- if you are running MySQL on a Mac OSX, try changing '''$CFG->dbhost''' from 'localhost' to '127.0.0.1'
'''See also''': MySQL page on [http://dev.mysql.com/doc/refman/5.0/en/common-errors.html common errors] which lists several possible scenarios for connection failure, with advice on how to fix the problems.

==I can't log in with message "Please verify that the current setting of session.save_path is correct" ==

This error occurs when PHP is having problems saving its session files. You may also see these other error messages displayed on the screen or in your log files:

Warning: Unknown: open(some-path/sessions/sess_acbf942a7399db3489ffa910e35d5242, O_RDWR)
failed: Permission denied (13) in Unknown on line 0

Warning: Unknown(): open(some-path/sessions/sess_acbf942a7399db3489ffa910e35d5242, O_RDWR)
failed: No space left on device (28) in Unknown on line 0

Warning: Unknown: Failed to write session data (files). Please verify that the current
setting of session.save_path is correct (some-path/sessions) in Unknown on line 0

To temporarily bypass these errors, '''use database sessions''' by editing your [[Configuration_file | moodle configuration file]] and adding this line:

$CFG->dbsessions = true;

Database sessions may overload your mysql database and are not ideal in a shared hosting environment, so if this solves the problem, you can start fixing the problem as follows:
* Check '''access rights'''. The session.save_path should be accessible by the apache user. Try this command:

chown -R apache:apache some-path/sessions

:This assumes that 'apache' is the name of the user your webserver runs under - it could also be 'nobody'.
* Check the '''permissions''' to the directory that PHP is trying to save to (session.save_path = some-path/sessions). Set the permissions initially to 0777 (everyone read, write, execute) with this command:

chmod -R 0777 some-path/sessions

:If this fixes the problem, reduce the permissions (700 is recommended).

'''See also''': Session problems can be specific to your server environment. As an example, see [http://moodle.org/mod/forum/discuss.php?d=55925#254596 this forum discussion] about session problems with Lycos hosting.

==Error: A server error that affects your login session was detected==
If restarting your browser and logging in again to your Moodle site does not work, see the Using Moodle [http://moodle.org/mod/forum/discuss.php?d=73716 forum discussion about this error message].

If this was received at a Moodle.org site, the site could be in the process of updating. Please try the suggestion and/or wait and try it again. Or report it in [[Tracker]].

==Error: Failed opening required '/web/moodle/lib/setup.php'==

In your ''config.php'', the setting that you use for the dirroot variable must be the complete path from the root of your server's hard drive.

Sometimes people only use the path from their home directory, or relative to the root of the web server directory.

==Any text I add with an apostrophe (') or a quote (") causes errors or comes up with a slash added==

Problems caused by apostrophes are caused by incorrect "magic quotes" settings. Moodle requires the following settings in the php.ini file (which are usually the default):

magic_quotes_runtime = Off

Starting in 2.0 it is strongly recommended to disable magic quotes completely

magic_quotes_gpc = Off

Please see [[Installing Moodle]] for more details.

If you are using [[Debian_GNU/Linux_installation|Debian]] then the problem might be in the version of PHP that you have installed. Have a look at this [http://tracker.moodle.org/browse/MDL-9691 bug report ] to see if it matches your situation.

==My pages show fatal errors such as : Parse error, call to undefined function: get_string()==

If you see errors like:

Parse error: parse error, unexpected T_VARIABLE in /path/to/moodle/config.php on line 94
Fatal error: Call to undefined function: get_string() in /path/to/moodle/mod/resource/lib.php
on line 11

then you have probably left out a semi-colon or closing quote from a line in ''config.php'' (previous to line 94).

Another possibility is that you edited ''config.php'' in a program like Word and saved it as a HTML web page, instead of using a plain text editor like Notepad.

Another thing to check, particularly if you are using 3rd party modules or plugins, is whether any of the php scripts use short open tags (<? ?>) instead of proper ones (<?php ?>). Short tags are bad for various reasons, so first contact the author of that extension to tell them about the problem. Then either replace short tags with conventional ones, or set this line in php.ini:

short_open_tag = On

You should never find short tags in core moodle code. If you do, please file a bug in the bug tracker.

==Serious Error! Could not set up the site!==

Please refer to the Using Moodle forum discussion [http://moodle.org/mod/forum/discuss.php?d=32071 Serious Error! Could not set up the site!].

==When I go to the admin page, I get told to make dirroot blank!==

If you see errors like this:

Please fix your settings in config.php:
You have: $CFG->dirroot = "/home/users/fred/public_html/moodle";
but it should be: $CFG->dirroot = "";

then you have encountered a small bug that occurs on some servers. The problem is with the error-checking mechanism, not with your actual path. To fix it, find this line (line 66) in the file ''admin/index.php'':

if ($dirroot != $CFG->dirroot) {

and change it to this:

if (!empty($dirroot) and $dirroot != $CFG->dirroot) {

==When trying to add a resource I receive error messages==

Assuming you are using Apache, then it's quite likely that your setting in ''config.php'' for <code>$CFG->wwwroot</code> is different from the actual URL you are using to access the site. Also try turning off the ''secureforms'' variable in the security section of Administration >> Configuration >> [[admin/config|Variables]].

==Why do I keep getting error messages about "headers already sent"?==

If you see errors like this:

Warning: Cannot add header information - headers already sent by
(output started at /webs/moodle/config.php:87) in /webs/moodle/lib/moodlelib.php
on line 1322

Warning: Cannot add header information - headers already sent by
(output started at /webs/moodle/config.php:87) in /webs/moodle/lib/moodlelib.php
on line 1323

Warning: Cannot add header information - headers already sent by
(output started at /webs/moodle/config.php:87) in /webs/moodle/login/index.php
on line 54

you have blank lines or spaces after the final <code>?></code> in your ''config.php'' file. Sometimes text editors add these - for example Notepad on Windows - so you may have to try a different text editor to remove these spaces or blank lines completely.

==Error: "500:Internal Server Error"==
There are several possible causes for this error:

1. '''Syntax error''': There is a syntax error in your .htaccess or httpd.conf files. The way in which directives are written [http://httpd.apache.org/docs/1.3/howto/htaccess.html#when differs] depending on which file you are using. You can test for configuration errors in your Apache files using the command:
#apachectl configtest

2. '''PHPsuexec''': Your server does not support .htaccess files, especially if it is running PHPsuexec, which is an Apache module used for increasing the security of a site on a hosted system. In this situation:

- you may also see a 403: Forbidden error.

- the webserver executes under your own username and all files have a maximum permissions level of 755. Check that this is set for your Moodle directory in your control panel or (if you have access to the shell) use this command:
#chmod -R 755 moodle

- use a PHP.INI file instead of a .htaccess in the directory where the Moodle PHP script is being executed. For example: if you are receiving a memory exhausted error when your server is executing the file moodle/admin/cron.php, use a PHP.INI file to change your memory_limit and copy it to the moodle/admin directory. Remember that for PHP4, PHP.INI files are per-directory, so you'll need to copy it to each sub-directory. If you are using PHP5 or higher on a shared host, check with your host on whether they support custom PHP.INI files, and how to create them. The syntax used in a PHP.INI file is different from a .htaccess file and you need to take out php_value/php_flag at the beginning of the line and use an equals sign to assign a value, e.g.
php_value memory_limit 128M <-- .htaccess
memory_limit = 128M <-- php.ini equivalent

3. '''Incompatible directive''': You may have a directive in your .htaccess or httpd.conf files which are not compatible with your web server version. Check your webserver documentation.

==Error "403: Forbidden" ==

Check your webserver configuration. See also the section above "500:Internal Server Error".

==Fatal error allowed memory size exhausted. How do I increase my php memory limit?==
You will sometimes see an error message something like this:
Fatal error: Allowed memory size of 67108864 bytes exhausted
(tried to allocate xx bytes) in /var/www/moodle/yyyy.php
This error means that the php memory_limit value is not enough for the php script. The memory_limit value is the "allowed memory size" - 64M in the example above (67108864 bytes / 1024 = 65536 KB. 65536 KB / 1024 = 64 MB). You will need to increase the php memory_limit value until this message is not shown anymore. There are two methods of doing this.
*On a hosted installation, add the following line to your .htaccess file (or create one in the moodle directory if it does not already exist):
php_value memory_limit <value>M
Example: php_value memory_limit 40M
*If you have your own server with shell access, edit your php.ini file (make sure it's the correct one by checking in your phpinfo output) as follows:
memory_limit <value>M
Example: memory_limit 40M
* For later versions of Moodle you could be looking at figures in the region of 512M for all functions to work properly (backup and restore are particularly memory hungry). It is sensible to monitor the memory usage on your server if using these large settings.
Remember that you need to restart your web server to make changes to php.ini effective. An alternative is to disable the memory_limit by using the command ''memory_limit 0''.

==Error: "Could not create guest user record!"==

Most likely the database table mdl_user needs repairing. This may be done as follows using phpMyAdmin:

# Click the SQL tab.
# In the "Run SQL query/queries on database moodle" field type <code>REPAIR TABLE mdl_user</code>
# Click the Go button.

==Error: "Your session has timed out. Please login again."==

Please do one/all of the following:
* Try deleting cookies manually from your browser and close it down, then access your site again. Sometimes this clears up the problem.
* Check that your ''moodledata/sessions'' directory has write permissions. When you access Moodle a new file should be created there.
* If you are running two versions of Moodle on the same computer, set a cookie prefix in ''Administration > Server > [[Session handling]]''.

The discussion [http://moodle.org/mod/forum/discuss.php?d=46580 Your session has timed out. Please login again] has further suggested solutions.

==How can I fix just one bug, without upgrading my whole site?==

Suppose:
* You are running an older Moodle version.
* You are experiencing a particular bug.
* You have searched in the [http://tracker.moodle.org/ tracker], and found that your problem is MDL-abc, and that it has been fixed in the latest version.
* For some reason, you cannot upgrade your whole site, even though the latest version probably has security fixes.

Then, how can you get the fix for just this one bug, without upgrading your whole site? Well, if you are prepared to manually patch the code, you can probably get this information from the tracker. Please see [[How to fix just one bug without upgrading|this guide]].

==See also==

* [[:Category:Error]] for a list of Moodle error pages.

[[Category:FAQ]]
[[Category:Error]]

Development:Themes 2.0

2011-04-05T15:05:41Z

Howardsmiller: using image file extensions break pix_url()

{{Template:Themes}}{{Moodle 2.0}}Welcome to the new world of themes within Moodle 2.0!

This document explains how themes work in Moodle and is intended to help you create or modify most themes for Moodle 2.0.

==Introduction==

Moodle themes are responsible for much of the "look" of a Moodle site. They provide the CSS for colours, layouts, fonts and so on, and can also change the structural XHTML code below that.

A theme can either contain all the definitions (completely stand alone) or it can extend an existing theme with one or more customizations.

Most theme developers use the second method and simply add a few new CSS or layout definitions to their new theme. If a definition or element is not found in the new theme, it looks to the "parent" (or up the hierarchy of themes) to find one. It an easy way to achieve just about any look you want for a theme.

==What's new in 2.0==

The theme system was completely redesigned in Moodle 2.0. Known issues have been addressed and new features have been added to meet community requests.

Unfortunately it was not possible to maintain backward compatibility, so all Moodle 1.x themes need to be recreated for Moodle 2.0.

Major changes include:
* Clearer and more consistent CSS classes and IDs throughout all pages in Moodle
* Introduction of layout files (templates) describing overall layout HTML for many different types of pages in Moodle.
* Introduction of renderers, which produce the smaller "parts" of a HTML page. Advanced themes can choose to override these too if they choose.
* Introduction of standard methods for adding Javascript to themes.
* Easier control over icons and images in Moodle.
* The old "standard" theme has been split into two themes:
**'''base''' - contains absolutely basic layout, and
**'''standard''' - which adds CSS to the base theme to make it look like the old standard theme.
* Performance tuning: In normal production mode CSS files are combined into a single optimised file, and both CSS and JavaScript files are minimised to ensure there are no wasted connections or traffic. Files are heavily cached, but also versioned, so that users never need to clear their caches.

==The structure of a theme==

Some important things to know when building good themes:

# '''config.php''' - this file is required in every theme. It defines configuration settings and definitions required to make the theme work in Moodle. These include theme, file, region, default region and options.
# '''Layouts and layout files''' - in config.php there is one definition for each page type (see [[#theme_layouts_table|Appendix A: Theme layouts]] for a list of over 12 types). Each page type definition tells Moodle which layout file will be used, what block regions this page type should display and so on. The layout file contains the HTML and the minimum PHP required to display basic structure of pages. (If you know Moodle 1.9, it's like a combination of header.html and footer.html).
# '''The base theme''' - is not intended to be used for production sites. It sets up the simplest possible generic layout and includes only CSS essential to that layout ''or'' to Moodle as a whole. It tries not to make any unnecessary rules and makes as few assumptions as possible. It's the perfect base on which to start designing a theme, as there are very few colours, borders, margins, and alignments to override. You can just start adding what you need.

===Files and folders===
A theme's files are placed in a folder with under moodle/theme folder and have subfolders. They are laid out like this:

{| class="nicetable"
|-
! Directory
! File
! Description
|-
|
| /config.php
| Contains all of the configuration and definitions for each theme
|-
|
| /lib.php
| Contains speciality classes and functions that are used by theme
|-
|
| /renderers.php
| Contains any custom renderers for the theme.
|-
|
| /settings.php
| Contains custom theme settings. These local settings are defined by the theme allowing the theme user to easily alter something about the way it looks or operates. (eg a background colour, or a header image)
|-
| /javascript/
|
| All specialty JavaScript files the theme requires should be located in here.
|-
| /lang/
|
| Any special language files the theme requires should be located in here.
|-
| /layout/
|
| Contains the layout files for the theme.
|-
| /pix/
|
| Contains any images the theme makes use of either in CSS or in the layout files.
|-
| /pix
| /favicon.ico
| The favicon to display for this theme.
|-
| /pix
| /screenshot.jpg
| A screenshot of the theme to be displayed in on the theme selection screen.
|-
| /style
|
| Default location for CSS files.
|-
|
|/*.css
|CSS files the theme requires
|}

There are also several other places that stylesheets can be included from (see the CSS how and why section below).

==Theme options==
All theme options are set within the config.php file for the theme. The settings that are most used are: parents, sheets, layouts, and javascripts. Have a look at the '''[[#theme_options_table|theme options table]]''' for a complete list of theme options which include lesser used specialised or advanced settings.

===Basic theme config example===
Lets have a look at a basic theme configuration file and the different bits that make it up:
<code php>
$THEME->name = 'newtheme';

$THEME->parents = array(
'base'
);

$THEME->sheets = array(
'admin',
'blocks',
'calendar',
'course',
'grade',
'message',
'question',
'user'
);

$THEME->layouts = array(
'base' => array(
'theme' => 'newtheme',
'file' => 'general.php',
'regions' => array(),
),
'standard' => array(
'theme' => 'newtheme',
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
)
//.......
);

$THEME->javascripts_footer = array(
'navigation'
);
</code>

===Basic theme example settings explained===
First up you will notice everything is added to $THEME. This is the theme's configuration object, it is created by Moodle using default settings and is then updated by whatever settings you add to it.

The first setting, $THEME->name is the theme's name. This should simply be whatever your theme's name is, most likely whatever you named your theme directory.

$THEME->parents defines the themes that the theme will extend. In this case it is extending only the base theme.

After this is the $THEME->sheets array containing the names of the CSS stylesheets to include for this theme. Note that it is just the name of the stylesheet and does not contain the directory or the file extension. Moodle assumes that the theme's stylesheets will be located in the styles directory of the theme and have .css as an extension.

Next we see the $THEME->layouts definition. In this example, two layouts have been defined to override the layouts from the base theme. For more information see the [[#Layouts|layouts]] section below.

The final setting is to include a JavaScript file, as $THEME->javascripts_footer. Much like stylesheets, you only need to provide the files name. Moodle will assume it is in your themes JavaScript directory and be a .js file.

'''''Note''''': When you first begin writing themes, make sure you take a look at the configuration files of the other themes that get shipped with Moodle. You will get a good picture of how everything works, and what is going on in a theme, simply by reading it and taking notice of what it is including or excluding.

==CSS==
===Locations of CSS files===
First lets look at where CSS can be included from within Moodle:
; \theme\themename\styles\*.css : This is the default location for all of the stylesheets that are used by a theme and the place which should be used by a theme designer.

New theme developers should note that the order in which CSS files are found and included creates a hierarchy. This order ensures that the rules, within a theme's style sheets, take precedence over identical rules in other files that may have been introduced before. This can both extend another files definitions (see parent array in the config file) and also ensures that the current theme's CSS rules/definitions have the last say.

There are other locations that can be used (although very rarely) to include CSS in a page. A developer of a php file can manually specify a stylesheet from anywhere within Moodle, like the database. Usually, if code is doing this, it is because there is a non-theme config or plugin setting that contains information requires special CSS information. As a theme designer you should be aware of, but not have to worry about, these locations of CSS files. Here are some examples:

; {pluginpath}\styles.css e.g. \block\blockname\styles.css or \mod\modname\styles.css : Every plugin can have its own styles.css file. This file should only contain the required CSS rules for the module and should not add anything to the look of the plugin such as colours, font sizes, or margins other than those that are truly required.<br />Theme specific styles for a plugin should be located within the themes styles directory.
; {pluginpath}\styles_themename.css : This should only ever be used by plugin developers. It allows them to write CSS that is designed for a specific theme without having to make changes to that theme. You will notice that this is never used within Moodle and is designed to be used only by contributed code.

As theme designers, we will only use the first method of introducing CSS: adding rules to a stylesheet file located in the themes styles directory.

===Moodle's core CSS organisation===
The next thing to look at is the organisation of CSS and rules within a theme. Although as a theme designer it is entirely up to you as to how you create and organise your CSS. Please note that within the themes provided in the standard install by Moodle there is a very clear organisation of CSS.

First is the pagelayout.css file. This contains the CSS required to give the layouts their look and feel. It doesn't contain any rules that affect the content generated by Moodle.

Next is the core.css file. If you open up core you will notice that it contains all manner of general (usually simple) rules that don't relate to a specific section of Moodle but to Moodle as a whole.

There can also be rules that relate to specific sections. However, this is done only when there are only a handful of rules for that section. These small clusters of rules are grouped together and separated by comments identifying for which section each relates.

Finally there are all the other CSS files, you will notice that there is a file for each section of Moodle that has a significant collection of rules.

:For those who are familiar with Moodle 1.9 theme's, this organisation will be a big change. In 1.9, CSS was organised by its nature (for example: colours, layout, other).

===How to write effective CSS rules within Moodle===
In Moodle 2.0, writing good CSS rules is an incredibly important.

Due to performance requirements and browser limitations, all of the CSS files are combined into a single CSS file that gets included every time. This means that rules need to be written in such a way as to minimise the chances of a collision leading to unwanted styles being applied. Whilst writing good CSS is something most designers strive for we have implemented several new body classes and put more emphasis on developers for using classes more appropriately.

====The body tag====
As of Moodle 2.0 the ID tag that gets applied to the body will always be a representation of the URI. For example if you are looking at a forum posting and the URI is '/mod/forum/view.php' then the body tags ID will be '#page-mod-forum-view'.

As well as the body's ID attribute the URI is also exploded to form several CSS classes that get added to the body tag, so in the above example '/mod/forum/view' you would end up with the following classes being added to the body tag '.path-mod', '.path-mod-forum'. Note that '.path-mod-forum-view' is not added as a class, this is intentionally left out to lessen confusion and duplication as rules can relate directly to the page by using the ID and do not require the final class.

The body ID and body classes described above will form the bread and butter for many of the CSS rules you will need to write for your theme, however there are also several other very handy classes that get added to the body tag that will be beneficial to you once you start your journey down the rabbit hole that is themeing. Some of the more interesting classes are listed below.

* If JavaScript is enabled then 'jsenabled' will be added as a class to the body tag allowing you to style based on JavaScript being enabled or not.
* Either 'dir-rtl' or 'dir-ltr' will be added to the body as a class depending on the direction of the language pack: rtl = right to left, ltr = left to right. This allows you to determine your text-alignment based on language if required.
* A class will be added to represent the language pack currently in use, by default en_utf8 is used by Moodle and will result in the class 'lang-en_utf8' being added to the body tag.
* The wwwroot for Moodle will also be converted to a class and added to the body tag allowing you to stylise your theme based on the URL through which it was reached. e.g. http://sam.moodle.local/moodle/ will become '.sam-moodle-local—moodle'
* If the current user is not logged then '.notloggedin' will be added to the body tag.

What does all of this look like in practise? Well using the above example /mod/forum/view.php you would get at least the following body tag:
<code html4strict><body id=”page-mod-forum-view” class=”path-mod path-mod-forum” /></code>

====Writing your rules====
The best use of body ids and classes and writing selectors will reduce problems.

There are many specific classes used within Moodle. We try to put them everywhere where anyone may want to apply their own styles. It is important to recognise that no one developer can be aware of the all of the class names that have been used all throughout Moodle, let alone within all of the different contributed bits and pieces available for Moodle. It is up to the theme developer to write good rules and minimise the chances of a collision between rules because in this case good CSS is FAR more effective.

When starting to write rules make sure that you have a good understanding of where you want those rules to be applied, it is a good idea to make the most of the body classes mentioned above.
If you want to write a rule for a specific page make use of the body tag's ID, e.g.:

<code css>#page-mod-forum-view .forumpost {border:1px solid orange;)</code>

If you want to write a rule that will be applied all throughout the forum.:

<code css>.path-mod-forum .forumpost {border:1px solid orange;}</code>

The other very important thing to take into consideration is the structure leading up to the tag you want to style. Browsers apply conflicting styles with priority on the more specific selectors. It can be very beneficial to keep this in mind and write full selectors that rely on the structure of the tags leading to the tag you wish to style.

By making use of body id's and classes and writing selectors to take into account the leading structure you can greatly minimise the chance of a collision both with Moodle now and in the future.

==Layouts==
All themes are required to define the layouts they wish to be responsible for as well as create; however, many layout files are required by those layouts. If the theme is overriding another theme then it is a case of deciding which layouts this new theme should override. If the theme is a completely fresh start then you will need to define a layout for each of the different possibilities. For both situations these layouts should be defined within config.php.

It is also important to note that a new theme that will base itself on another theme (overriding it) does not need to define any layouts or use any layout files if there are no changes that it wishes to make to the layouts of the existing theme. The standard theme in Moodle is a good example of this as it extends the base theme simply adding CSS to achieve its look and feel.

So layouts... as mentioned earlier layouts are defined in config.php within $THEME->layouts. The following is an example of one such layout definition:
<code php>
$THEME->layouts = array(
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'theme' => 'base',
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
)
)
</code>
The first thing Moodle looks at is the name of the layout, in this case it is `standard` (the array key in PHP), it then looks at the settings for the layout, this is the theme, file, regions, and default region. There are also a couple of other options that can be set by a layout.

; theme : is the theme the layout file exists in. That's right you can make use of layouts from other installed themes. ''Optional''
; file : is the name of the layout file this layout wants to use. ''Required''
; regions : is the different block regions (places you can put blocks) within the theme. ''Required''
; defaultregion : is the default location when adding new blocks. '''Required if regions is non-empty, otherwise optional'''
; options : an array of layout specific options described in detail below. '''Optional'''

The '''theme''' is optional. Normally the the layout file is looked for in the current theme, or, if it is not there, in the parent theme. However, you can use a layout file from any other theme by giving the theme name here.

You can define whatever regions you like. You just need to pick an name for each one. Most themes just use one or both of '''side_pre''' and '''side_post''', which is like 'left side' and 'right side', except in right to left languages, when they are reversed. If you say in config.php that your the layout provides regions called 'fred' and 'barney', then you must call $OUTPUT->blocks_for_region('fred') and $OUTPUT->blocks_for_region('barney') somewhere in the layout file.

The final setting '''options''' is a special case that only needs to be set if you want to make use of it. This setting allows the theme designer to specify special options that they would like to create that can be later accessed within the layout file. This allows the theme to make design decisions during the definition and react upon those decisions in what ever layout file is being used.

One such place this has been used is infact within the base theme. If you take a look first at theme/base/config.php you will notice that several layouts specify options '''nonavbar''' and '''nofooter''' which can both be set to either true or false. Then if we take a look at theme/base/layout/general.php you will spot lines like the following:
<code php>
<?php
$hasnavbar = (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar());
$hasfooter = (empty($PAGE->layout_options['nofooter']));
?>
............
<?php if ($hasnavbar) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
What you are seeing here is the use of those settings from the layout within the layout file. In this case it is being used to toggle the display of the navigation bar and page footer.

==Layout files==
A layout file is a file that contains the core HTML structure for a layout including the header, footer, content and block regions.
For those of you who are familiar with themes in Moodle 1.9 this is simply header.html and footer.html combined.
Of course it is not all HTML, there are bits of HTML and content that Moodle needs to put into the page, within each layout file this will be done by a couple of VERY simple PHP calls to get bits and pieces including content.

The following is a very simple layout file to illustrate the different bits that make it up:
<code php>
<?php echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
<body id="<?php p($PAGE->bodyid) ?>" class="<?php p($PAGE->bodyclasses) ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<table id="page">
<tr>
<td colspan="3">
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php echo $OUTPUT->login_info(); echo $PAGE->headingmenu; ?></div>
</td>
</tr>
<tr>
<td>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</td>
<td>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</td>
<td>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</td>
</tr>
<tr>
<td colspan="3">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</td>
</tr>
</table>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

Lets assume you know a enough HTML to understand the basic structure above, what you probably don't understand are the PHP calls so lets look at them.
<code php>
<?php echo $OUTPUT->doctype() ?>
</code>
This occurs at the VERY top of the page, it must be the first bit of output and is responsible for adding the (X)HTML document type definition to the page. This of course is determined by the settings of the site and is one of the things that the theme designer has no control over.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we have started writing the opening html tag and have asked Moodle to give us the HTML attributes that should be applied to it. This again is determined by several settings within the actual HTML install.

<code php>
<?php echo $PAGE->title ?>
</code>
This gets us the title for the page.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
This very important call gets us the standard head HTML that needs to be within the HEAD tag of the page. This is where CSS and JavaScript requirements for the top of the page will be output as well as any special script or style tags.

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
</code>
Much like the html tag above we have started writing the body tag and have asked for Moodle to get us the desired ID and classes that should be applied to it.

<code php>
<h1 class="headermain"><?php echo $PAGE->heading; ?></h1>
<div class="headermenu"><?php echo $OUTPUT->login_info(); echo $PAGE->headingmenu; ?></div>
</code>
Here we are creating the header for the page. In this case we want the heading for the page, we want to display the login information which will be the current users username or a link to log in if they are not logged in, and we want the heading menu if there is one.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
Here we get the HTML to display the blocks that have been added to the page. In this case we have asked for all blocks that have been added to the area labelled ''side-pre''.

<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This is one of the most important calls within the file, it determines where the actual content for the page gets inserted.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we get the HTML to display the blocks that have been added to the page. In this case we have asked for all blocks that have been added to the area labelled ''side-post''.

<code php>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</code>
This final bit of code gets the content for the footer of the page. It gets the login information which is the same as in the header, a home link, and the standard footer HTML which like the standard head HTML contains all of the script and style tags required by the page and requested to go in the footer.

'''''Note''''': Within Moodle 2.0 most of the JavaScript for the page will be included in the footer. This greatly helps reduce the loading time of the page.

When writing layout files think about the different layouts and how the HTML that each makes use of will differ. You will most likely find you do not need a different layout file for each layout, most likely you will be able to reuse the layout files you create across several layouts. You can of course make use of layout options as well to further reduce the number of layout files you need to produce.

Of course as mentioned above if you are customising an existing theme then you may not need to create any layouts or layout files at all.

'''$OUTPUT''' is an instance of the '''core_renderer''' class which is defined in lib/outputrenderers.php. Each method is clearly documented there, along with which is appropriate for use within the layout files.

'''$PAGE''' is an instance of the '''moodle_page''' class defined in lib/pagelib.php. Most of the things you will want to use are the properties that are all documented at the top of the file. If you are not familiar with PHP properties, you access them like $PAGE->activityname, just like fields of an ordinary PHP object. (However, behind the scenes, some magic is going on, and the value you get is produced by calling a function. Also, you cannot change these values, they are read-only. However, you don't need to understand all that if you are just using these properties in your theme.)

==Making use of images==
Right at the start when listing the features of the new themes system one of the features mentioned was the ability to override any of the standard images within Moodle from within your theme. At this point we will look at both how to make use of your own images within your theme, and secondly how to override the images being used by Moodle.
So first up a bit about images within Moodle,

# Images you want to use within your theme '''need''' to be located within your theme's pix directory.
# You can use sub directories within the pix directory of your theme.
# Images used by Moodle's core are located within the pix directory of Moodle.
# Modules, blocks and other plugins should also store there images within a pix directory.

So making use of your own images first up. Lets assume you have added two image files to the pix directory of your theme.

* /theme/yourthemename/pix/imageone.jpg
* /theme/yourthemename/pix/subdir/imagetwo.png

Notice that one image is a JPEG image, and the second is a PNG. Also the second image is in a subdirectory.

The following code snippet illustrates how to make use of your images within HTML, such as if you wanted to use them within a layout file.
<code php>
<img src="<?php echo $OUTPUT->pix_url('imageone', 'theme');?>" alt="" />
<img src="<?php echo $OUTPUT->pix_url('subdir/imagetwo', 'theme');?>" alt="" />
</code>

'''DO NOT''' include the image file extension. Moodle will work it out automatically and it will not work if you do include it.

In this case rather than writing out the URL to the image we use a method of Moodle's output library. Its not too important how that functions works but it is important that we use it as it is what allows images within Moodle to be over-rideable.

The following is how you would use the images from within CSS as background images.
<code css>
.divone {background-image:url([[pix:theme|imageone]]);}
.divtwo {background-image:url([[pix:theme|subdir/imagetwo]]);}
</code>
If this case we have to use some special notations that Moodle looks for. Whenever Moodle hands out a CSS file it first searches for all ''[[something]]'' tags and replaces them with what is required.

The final thing to notice with both of the cases above is that at no point do we include the images file extension.
The reason for this leads us into the next topic, how to override images.

From within a theme you can VERY easily override any standard image within Moodle by simply adding the replacement image to the theme's pix directory in the same sub directory structure as it is in Moodle.
So for instance we wanted to override the following two images:
# /pix/moodlelogo.gif
# /pix/i/user.gif
We would simply need to add our replacement images to the theme in the following locations
# /theme/themename/pix/moodlelogo.gif
# /theme/themename/pix/i/user.gif
How easy is that!

Now the other very cool thing to mention is that Moodle looks for not just replacements of the same image type (jpg, gif, etc...) but also replacements in any image format. This is why above when working with our images we never specified the images file extension.
This means that the following would also work:
# /theme/themename/pix/moodlelogo.png
# /theme/themename/pix/i/user.bmp

For a more detailed description of how this all works see the page on [[Development:Themes_2.0_How_to_use_images_within_your_theme|using images within your theme]]

==Unobvious Things==
===Getting Your Theme to Appear Correctly in Theme Selector===
If you follow the examples on this page to the letter, when you go to the Theme Selector page you may be discouraged to find that your theme does not appear like the other themes do. In fact, instead of your theme's name, you will see something along the lines of <nowiki>[[pluginname]]</nowiki>.

To correct this, you must add the /lang/en/theme_THEMENAME.php file, where THEMENAME is the name of the theme folder. Inside that file, add the string "$string['pluginname'] = 'THEMENAME'; ". Make THEMENAME the name of your theme, however you want it displayed in the Theme selector.

The screenshot for the theme should be about 500x400 px.

===Required theme divs===

Some parts of Moodle may rely on particular divs, for example the div with id 'page-header'.

Consequently all themes must include at least the divs (with the same ids) that are present in the 'base' theme.

Missing out these elements may result in unexpected behaviour within specific modules or other plugins.

==Appendix A==
===Theme options as of April 28th, 2010===
{| class="nicetable" id="theme_options_table"
|-
! Setting
! Effect
|-
| $THEME->'''csspostprocess'''
| Allows the user to provide the name of a function that all CSS should be passed to before being delivered.
|-
| $THEME->'''editor_sheets'''
| An array of stylesheets to include within the body of the editor.
|-
| $THEME->'''enable_dock'''
| If set to true the side dock is enabled for blocks
|-
| $THEME->'''hidefromselector'''
| Used to hide a theme from the theme selector (unless theme designer mode is on). Accepts true or false.
|-
| $THEME->'''filter_mediaplugin_colors'''
| Used to control the colours used in the small media player for the filters
|-
| $THEME->'''javascripts'''
| An array containing the names of JavaScript files located in /javascript/ to include in the theme. (gets included in the head)
|-
| $THEME->'''javascripts_footer'''
| As above but will be included in the page footer.
|-
| $THEME->'''larrow'''
| Overrides the left arrow image used throughout Moodle
|-
| $THEME->'''layouts'''
| An array setting the layouts for the theme
|-
| $THEME->'''name'''
| Name of the theme. Most likely the name of the directory in which this file resides.
|-
| $THEME->'''parents'''
| An array of themes to inherit from
|-
| $THEME->'''parents_exclude_javascripts'''
| An array of JavaScript files NOT to inherit from the themes parents
|-
| $THEME->'''parents_exclude_sheets'''
| An array of stylesheets not to inherit from the themes parents
|-
| $THEME->'''plugins_exclude_sheets'''
| An array of plugin sheets to ignore and not include.
|-
| $THEME->'''rarrow'''
| Overrides the right arrow image used throughout Moodle
|-
| $THEME->'''renderfactory'''
| Sets a custom render factory to use with the theme, used when working with custom renderers.
|-
| $THEME->'''resource_mp3player_colors'''
| Controls the colours for the MP3 player
|-
| $THEME->'''sheets'''
| An array of stylesheets to include for this theme. Should be located in the theme's style directory.
|}
===The different layouts as of August 17th, 2010===
{| class="nicetable" id="theme_layouts_table"
|-
! Layout
! Purpose
|-
| base
| Most backwards compatible layout without the blocks - this is the layout used by default.
|-
| standard
| Standard layout with blocks, this is recommended for most pages with general information.
|-
| course
| Main course page.
|-
| coursecategory
| Use for browsing through course categories.
|-
| incourse
| Default layout while browsing a course, typical for modules.
|-
| frontpage
| The site home page.
|-
| admin
| Administration pages and scripts.
|-
| mydashboard
| My dashboard page.
|-
| mypublic
| My public page.
|-
| login
| The login page.
|-
| popup
| Pages that appear in pop-up windows - no navigation, no blocks, no header.
|-
| frametop
| Used for legacy frame layouts only. No blocks and minimal footer.
|-
| embedded
| Embeded pages, like iframe/object embedded in moodleform - it needs as much space as possible
|-
| maintenance
| Used during upgrade and install. 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.
|-
| print
| Used when the page is being displayed specifically for printing.
|}

==See also==

* [[Development:Themes 2.0 creating your first theme]] - A quick step by step guide to creating your first theme.
* [[Development:Themes 2.0 overriding a renderer]] - A tutorial on creating a custom renderer and changing the HTML Moodle produces.
* [[Development:Themes 2.0 How to use images within your theme]] - Explains how to use and override images within your theme.
* [[Development:Themes 2.0 adding a settings page]] - Looks at how to add a setting page making your theme easily customisable.
* [[Development:Themes 2.0 extending the custom menu]] - Customising the custom menu.
* [[Development:Themes 2.0 how to make the dock horizontal]] - Modifying the dock to make it horizontal.
* [[Development:Themes 2.0 adding_upgrade_code]]
* [[Development:Styling and customising the dock]] - How to style and customise the dock.
* [[Development:Theme changes in 2.0]]
* [[Development:Using jQuery with Moodle 2.0]]
* [http://www.youtube.com/watch?v=OvaU54uh-qA New themes in Moodle 2.0 video]

[[de:Designs 2.0]]
[[es:Temas 2.0]]

Administrator documentation

2011-03-18T10:49:03Z

Howardsmiller: /* Unix/Linux-based */

The purpose of this page is to list useful links by general topics for administrators of a Moodle site.
__TOC__

== Installation & Upgrading ==

*[[Installation Quickstart]] for an overview of the installation steps
*[[Installing Moodle]] for detailed installation instructions
*[[Installation FAQ]]
*[[Installing AMP|Options for installing Apache, MySQL and PHP]]
*[[Upgrading|Upgrading Moodle]]
*[[Installing contributed modules or plugins]]

== System-specific Instructions & Packages ==

===Unix/Linux-based===
* [[SUSE Linux Server 10|Automated Installation Guide for SUSE Linux Enterprise Server 10]] operating system
* [[RedHat Linux installation|Step-by-step Installation Guide for RedHat]] operating system
* [[Debian GNU/Linux installation|Step-by-step Installation Guide for Debian GNU/Linux]] operating system
* [[Step-by-step Installation Guide for Ubuntu]]
* [[Manual installation of Moodle 2.0 on Mythbuntu using Git]]
* [[Manual_installation_on_Ubuntu|Manual Installation on Ubuntu]]
* [[Step-by-step Install Guide for Zenwalk-5.0|Step-by-step Installation Guide for Zenwalk-5.0]]
* [[OLPC XS installation|Step-by-step Installation Guide for the One Laptop per Child XS Server (Beta)]]
* [[Step-by-step Install Guide for Solaris 10 with Oracle 10|Step-by-step Installation Guide for Solaris 10 with Oracle 10]]
* [[Installation Guide for Installing on Amazon EC2]]

===Windows===
* [[Windows installation|Windows installations with instructions for Windows NT/2000/2003 servers]]
* [[Windows installation using XAMPP|Windows installation using XAMPP: Apache, MySQL and PHP]]
* [[Development:Windows_Installer_anywhere|MoodleAnywhere]] another Windows installation package
* [[Installing Moodle on Windows Vista]] - how to
* [http://www.bfcnetworks.com/whitepapers/installing-moodle-on-windows-server-iis-sql/ Installing Moodle on Windows Server 2008 x86]
* [http://www.bfcnetworks.com/whitepapers/installing-moodle-on-windows-server-2008-r2-x64-sql-iis/ Installing Moodle on Windows Server 2008 R2]
* [http://www.bfcnetworks.com/whitepapers/implementing-moodle-on-a-windows-high-availability-environment// Implementing Moodle on a Windows High Availability Environment] Implementing Moodle 1.9 on 2 Microsoft Load Balanced Web Front End Server and a Microsoft SQL Server 2008 R2 Cluster environment

Moodle 2
* [http://www.bfcnetworks.com/whitepapers/installing-moodle-2-on-windows-server-mysql-php-and-iis7/ Installing Moodle 2 on Windows Server, MySQL, PHP and IIS7]
* [http://www.bfcnetworks.com/whitepapers/installing-moodle-2-on-windows-server-2008-r2-x64-sql-iis/ Installing Moodle 2 on Windows Server, Microsoft SQL Server, PHP and IIS7]

===Mac===
* [[Step by Step Installation on a Mac OS X Server|Step by step Installation on a Mac OS X Server 10.5/10.6]]
* [[Complete Install Packages for Mac OS X | Complete Install Packages for Mac OS X Clients 10.4/10.5/10.6]]
* [[Step-by-step Guide for Installing Moodle on Mac OS X 10.4 Client|Step by Step Installation on a Mac OS X 10.4 Client using the internal web server]]

===Web Hosts===
* [[1and1_MySQL_installation | Installation on '''1and1''' web hosting]]
* [[powweb_MySQL_installation | Step-by-step Installation on '''Powweb''' web hosting]]
* [[Step-by-step Installation using the old version of CPanel]]
* [[Step-by-step Installation using the new version of CPanel]]

===Appliances===
Some users may prefer to skip manual installation by using a pre-integrated [[Moodle appliance]].

===Database===
* [[Installing Oracle for PHP]]
* [[Installing MSSQL for PHP]]
* [[Installing Postgres for PHP]]

===Plugins===
* [[Installing contributed modules or plugins]]

==Security, Performance and Roles==

*[[Security]] contains important security procedures for a production site
*[[Performance]] for ideas on improving the speed of your installation
*[[Manage roles]] For Moodle 1.7 and later.
*[[Reducing spam in Moodle]]
*[[suhosin]] is an advanced protection system for PHP installation. It was designed to protect servers and users from known and unknown flaws in PHP applications and the PHP core.
*[[nagios]] Open source software to monitor servers

== FAQs ==

*[[Installation FAQ]]
*[[Beginning Administration FAQ]]
*[[Administration FAQ]]
*[[Performance FAQ]]
*[[Backup and restore FAQ]]
*[[Errors FAQ]]
*[[:Category:FAQ|List of FAQs]]

== Configuration Settings ==
=== Site administration setting===
[[Site administration block]] contains most site configuration settings including:
*[[Front Page settings]]- initial or home page of a Moodle site
*[[Themes]] - user interface packages of XHTML and CSS controls
*[[Language]] - default and additional language packs
*[[Activity modules administration]]
*[[Blocks administration]]
*[[Filters]] - Text and Multimedea plugins
*[[Backup settings]]
*[[HTML editor settings]]
*[[Calendar settings]]
*[[Maintenance mode]]
*[[Notification page]] used to update versions
*[[Settings block]] Moodle 2.0 site settings location

===Other settings===
*[[Course settings]] for course home page configuration
**Each type of [[Activities|activity]], [[resource]] and [[:Category:Block|block]] has their own settings
*Older versions settings
**[[Site settings]] pre 1.7
**[[Variables]] pre 1.6
**[[Location of admin settings in 1.7|Comparison between configuration settings in Moodle 1.6 & 1.7]]

==User Management==

*[[Authentication]] of user on a site
*[[Add new user|Add a new user]] - on a site
*[[Upload users]] - from a file to a site, and into existing course and group, some existing user global updates
*[[User_profile_fields]]
*[[Enrolment plugins]]
**[[Flat file]] - enrol existing users in a course
*[[Roles and capabilities|Assigning user a role]] - typical assignments include:
**[[Students|Enrol students in a course]]
**[[Unenrolment]] Student
**[[Courses (administrator)|Assign teachers]] - to a course
**[[Assign creators|Assign course creators]] - in a site
**[[Assign administrators]] - in a site

==Other==

*[[Courses (administrator)|Courses]] and [[Course formats|course formats]]
*[[Reports (administrator)]] and [[Logs]]
*[[Site files]]
*[[Moodle database|Moodle site database]]
*[[Environment]]
*[[MNet|Moodle Network]] and Moodle [[Community hub]]
*[[Streaming Media]]
*[[Case studies (administrator)]]
*[[Anti-virus]]
*[[System Monitoring and Server Statistic Software]]
*[[Integrate Moodle, LDAP and SIMS.net]]
*[[How to rebuild context paths]]
*[[Hacking the Moodle 2.0 database transfer script to convert a Moodle 1.9 site]]
*[[Category:ProxyProblems]]

==See also==

*[[:Category:Administrator | Index of all Administrator-related pages]]
*[[Integrations]]
*[[CVS for Administrators]]
*[[Email processing]]
*[[Search engine optimization]]
*[[Messaging]]
*[[Migration]]
*[[Metacourses]]
*[[Block layout]]
*[[Customizing Moodle]]
*[[Administrator do's and don'ts]]
*[[Using Moodle book]] Chapter 16: Moodle Administration
*[[Administration hacks]]
*[[Git]] Version control, upgrading

[[Category: Administrator]]
[[cs:Rukověť správce]]
[[es:Documentación para Administradores]]
[[eu:Kudeatzaileentzako dokumentazioa]]
[[fr:Documentation administrateur]]
[[ja:管理者ドキュメント]]
[[ko:관리자 문서]]
[[nl:Documentatie voor beheerders]]
[[pt:Documentação para administradores]]
[[ru:Администраторам]]
[[sk:Dokumentácia pre správcov]]
[[zh:管理员文档]]
[[pl:Administrator documentation]]
[[fi:Ylläpitäjän opas]]
[[de:Dokumentation für Administratoren]]

Development:JavaScript guidelines

2011-02-18T13:26:04Z

Howardsmiller: /* Getting Moodle to load your JavaScript files */

{{Moodle 2.0}}

These guidelines can only be applied fully from Moodle 2.0 onwards, because they rely on our new API to facilitate use of JavaScript.

When writing JavaScript for earlier versions of Moodle, please try to follow these guidelines in spirit and use the '''require_js''' function in place of $PAGE->requires->js_module/yui2_lib.

==General principles==

===Moodle should be usable without JavaScript===

Everything in Moodle should work with JavaScript turned off. This is important for accessibility, and in line with the principles of [[Development:Unobtrusive_Javascript|unobtrusive JavaScript]] and [[Development:Progressive_enhancement|progressive enhancement]].

===Minimise inline JavaScript===

Almost all JavaScript code should be in separate .js files. There should be the smallest possible amount of JavaScript inline in the HTML code of pages.

The only <script> tags in the HTML should be
# <script src=... tags to include the necessary .js files.
# Simple function calls to trigger initialisation and pass data from PHP to JavaScript. For example <script type="text/javascript">initialise_my_widget('some', 'data', 123);</script>.

Even these small amounts of JS you should not output directly. They will be generated automatically by calls to the $PAGE->requries->js_init_call() API. See below for details.

You should not use old-fashioned onXXX="event_handler" attributes in the HTML. Use Modern DOM events. The YUI events library makes this easy.

=== JavaScript libraries ===

* The official JavaScript library for Moodle is [[Development:YUI|YUI]]. That may not be your favourite, but it's the one that was chosen after careful research, so live with it.

* Moodle also has its own JavaScript library code, packaged into in various JavaScript modules.

* Moodle uses the '''TinyMCE''' HTML editor.

===When to include the JavaScript===

As per [http://developer.yahoo.com/performance/rules.html Yahoo's best practice guidelines], load and execute the JavaScript as late as possible, ideally the script tags should be the last thing before the </body> close tag. (This is the default behaviour with Moodle's JavaScript handling functions like $PAGE->requries->js_init_call().)

Since everything should work without JavaScript, load and initialising your scripts only after everything else on the page has loaded should not be a problem and will increase the perceived page-load performance for users.

===Minimise the number of .js files===

Try not to use too many different .js files. Each separate file that the browser has to load incurs an overhead.

On the other hand, organise the JavaScript logically to ease maintenance, and don't include large amounts of irrelevant JavaScript code. Code that is loaded but never used is a waste of time.

So, if you are writing a new module that needs its own JavaScript, try starting with a single file mod/mymod/module.js. If you find that you are writing a lot of JavaScript that is only needed when the teacher edits your module, but is not needed by students, then consider splitting that code into a separate file like mod/mymod/edit.js, and only including it where needed.

==How to achive these general principles in Moodle==

The rest of this page explains how you can achieve the above goals. Note that this particularly applies to loading and using the YUI 3 library which is Moodle 2.0's default. You should check which version of YUI Moodle is using as it may lag behind the latest YUI release (and, hence, the documentation).

===Getting Moodle to load your JavaScript files===

Everything required by the current page is tracked by the $PAGE->requires object, which is an instance of the [http://phpdocs.moodle.org/HEAD/moodlecore/page_requirements_manager.html page_requirements_manager] class defined in lib/outputrequirementslib.php.

The most important method in this class is the ->js_init_call(...) method. You use it like this:

<code php>
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'));
</code>

Note that this will implicitly load the JavaScript code in mod/mymod/module.js, and then call the M.mod_mymod.init_something function passing four string arguments 'some', 'data', 'from', 'PHP'. You can pass any PHP type as an argument. The PHP values are encoded with json_encode before being passed to JavaScript, so numbers, strings, arrays and objects all work.

Sometimes, the code in the JavaScript module mod/mymod/module.js may require some other JavaScript libraries to be loaded, or it may require some language strings. In that case you need to use the full form of js_init_call:

<code php>
$jsmodule = array(
'name' => 'mod_mymod',
'fullpath' => '/mod/mymod/module.js',
'requires' => array('base', 'io', 'node', 'json'),
'strings' => array(
array('something', 'mymod'),
array('confirmdelete', 'mymod'),
array('yes', 'moodle'),
array('no', 'moodle')
)
);
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'), false, $jsmodule);
</code>
(Naturally, it would be a good idea to put the definition of the $jsmodule array somewhere central like in the locallib.php file.)

The third (boolean) parameter is defined as "Wait for DOM Ready".

The libraries in the 'requires' sub-array are YUI3 (or YUI2) libraries. Moodle contains YUIs 'phploader' which understands what the library dependencies are, so this is all taken care of for you.

The strings are Moodle language strings. In order for Moodle to have correctly determined the user's language, you should only call js_init_call after the call to require_login, which sets the current course, and ensures the user is logged in.
Strings that are passed to Javascript in this way are then available from Javascript using M.util.get_string(), which works just like the PHP function.

$PAGE->requires keeps track of which files have been included. For example if two other modules both require the YUI base module, then it is only included once.

Your 'module.js' file in your plugin's directory will look something like this:

<code javascript>
M.mod_mymod = {};

M.mod_mymod.init = function(Y) {

// example to submit a form field on change
Y.on('change', function(e) {
Y.one('#mform1').submit();
}, '#id_fieldname' );
};
</code>

''mod_mymod'' needs changed to reflect the plugin type (see [[Development:Frankenstyle]]) and the name of your plugin throughout.

===JavaScript coding style===

Moodle JavaScript code should should follow the same [[Development:Coding_style|coding style as Moodle PHP code]], allowing for the differences between PHP and JavaScript.

For example, all the rules on ''function_names'', ''class_names'' and ''variablenames'' apply. You should document your code with [http://jsdoc.sourceforge.net/ JSDoc] comments. Layout your JavaScript expressions and statements like the equivalent PHP ones.

Normally, your .js files should simply define things like functions, classes and variables. When the file is loaded, no JavaScript code should actually be executed that has any effect unless it is the sort of code that can safely be executed once per HTML page. This is so that it plays nicely with the require_once-like behaviour of $PAGE->requires->js.

Do not pollute the global JavaScript name-space. Try to package your JavaScript into objects, and put all objects inside the global M object, like the M.mod_mymod example above.

===Different content when JavaScript is on or off===

Remember the overriding principals that everything should work with JavaScript off, and we should adopt a [[Progressive enhancement]] approach. However, there are valid reasons why sometimes you need different content with JavaScript is on or off. We can break it down into three cases:

====Content that should only be visible with JavaScript off====

An example of this is the automatic search when you are looking for a user to assign a role to. With JavaScript on, the search automatically starts after a delay. With JavaScript off, we want an explicit Search button visible.

To handle this case, Moodle automatically add a class 'jsenabled' to the body tag using JavaScript. So you just need to add a rule like
<code css>
body.jsenebled .mywidget .submitbutton {
display: none;
}
</code>
to the stylesheet, and the button will be invisible if JavaScript is enabled.

An alternative strategy is to remove the particular bits of HTML from the page using DOM methods. However, if your JavaScript is only loaded at the end of the page, it may take some time for the extra content to disappear, which leads to a disconcerting flicker in the page.

Yet another approach is the old-fashioned <noscript> tag.

====Content that needs to be visible right away when JavaScript is on====

An example is the <nowiki>[+] or [-]</nowiki> icon that can be used to expand/collapse each block if JavaScript is on.

We can divide this into two subcases:

=====Content generated by PHP code=====

Where the HTML for the JavaScript only widget is generated by PHP, we can make it invisible when JavaScript is off using just CSS:
<code css>
.mywidget {
display: none;
}
body.jsenabled .mywidget {
display: block;
}
</code>
However, it could be argued that this approach is not really progressive enhancement.

=====Content generated by JavaScript code=====

This is more in keeping with progressive enhancement, and this is the way that the expand/collapse block icon is handled.

We build the icon using DOM methods. The only problem is that as the JavaScript is loaded in the footer, there is a small delay before the icons appear. Since when the icons appear, they do not cause other content on the page to move around, that is OK. Also, this delayed appearance is becoming more common on the web. For example, on http://twitter.com/, some things only appear a moment after the main part of the page has finished loading.

However, it the delayed appearance is really a problem, then the only solution is to embed the JavaScript that generates the extra content in the middle of the HTML, using the js_writer class.

====Content that only appears when the user does something, when JavaScript is on====

An example of this is something like file picker dialog that appears when you add an image to some content in the HTML editor, or the one that pops up when you click 'Add new question' in the quiz editing interface.

We have the same two sub-cases:

=====Content generated by PHP code=====

In this case, you need to make sure the content is always covered by a ''display: none;'' rule in the CSS, but then when the user takes an action like clicking a button to reveal the extra content, you need to override that class name some how, perhaps by adding or removing a className using JavaScript.

=====Content generated by JavaScript code=====

In this case, there is no problem. When the use triggers the extra content to appear, it is constructed using DOM methods. There may be a tiny delay, but the chances are that it will hardly be noticeable to the human eye.

If the content generation may be slow (perhaps because it is waiting for an Ajax request) then you should display a progress icon. See, for example, the loading of the tooltip for help icons.

===Don't break XHTML strict!===

Remember that all Moodle output must be [[Development:XHTML|XHTML strict]], and that means that the HTML output must be well-formed XML. Inline JavaScript is a great way to break that. (JavaScript uses the < and & symbols that must be escaped in XML.) Therefore any JavaScript inline in the HTML should be escaped in a CDATA section:

<code xml>
<script type="text/javascript">
//<![CDATA[

// Your JavaScript code goes here.

//]]>
</script>
</code>

Of course, if you are following the above guidelines and putting most of your JavaScript in separate .js files, and using $PAGE->requires->js_init_call, then this is taken care of for you automatically.

==Testing==

JavaScript support varies a lot between browsers. JavaScript needs to be tested in IE, Firefox and Safari. Ideally, Moodle will support [http://developer.yahoo.com/yui/articles/gbs/ all the browsers that YUI does].

==See also==

* [[Development:Coding|The rest of Moodle coding guidelines]]
* [http://developer.yahoo.com/yui/ YUI documentation]
* [[Javascript FAQ]]
* [[Javascript and YUI 3 FAQ]]
* [[Development:Unobtrusive Javascript]]
* [[Development:JavaScript functions]]
* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]

[[Category:Coding guidelines|JavaScript guidelines]]
[[Category:Javascript|JavaScript guidelines]]
[[Category:AJAX|JavaScript guidelines]]

[[ja:開発:Javaスクリプトガイドライン]]

Development:JavaScript guidelines

2011-02-18T13:22:54Z

Howardsmiller: /* How to achive these general principles in Moodle */

{{Moodle 2.0}}

These guidelines can only be applied fully from Moodle 2.0 onwards, because they rely on our new API to facilitate use of JavaScript.

When writing JavaScript for earlier versions of Moodle, please try to follow these guidelines in spirit and use the '''require_js''' function in place of $PAGE->requires->js_module/yui2_lib.

==General principles==

===Moodle should be usable without JavaScript===

Everything in Moodle should work with JavaScript turned off. This is important for accessibility, and in line with the principles of [[Development:Unobtrusive_Javascript|unobtrusive JavaScript]] and [[Development:Progressive_enhancement|progressive enhancement]].

===Minimise inline JavaScript===

Almost all JavaScript code should be in separate .js files. There should be the smallest possible amount of JavaScript inline in the HTML code of pages.

The only <script> tags in the HTML should be
# <script src=... tags to include the necessary .js files.
# Simple function calls to trigger initialisation and pass data from PHP to JavaScript. For example <script type="text/javascript">initialise_my_widget('some', 'data', 123);</script>.

Even these small amounts of JS you should not output directly. They will be generated automatically by calls to the $PAGE->requries->js_init_call() API. See below for details.

You should not use old-fashioned onXXX="event_handler" attributes in the HTML. Use Modern DOM events. The YUI events library makes this easy.

=== JavaScript libraries ===

* The official JavaScript library for Moodle is [[Development:YUI|YUI]]. That may not be your favourite, but it's the one that was chosen after careful research, so live with it.

* Moodle also has its own JavaScript library code, packaged into in various JavaScript modules.

* Moodle uses the '''TinyMCE''' HTML editor.

===When to include the JavaScript===

As per [http://developer.yahoo.com/performance/rules.html Yahoo's best practice guidelines], load and execute the JavaScript as late as possible, ideally the script tags should be the last thing before the </body> close tag. (This is the default behaviour with Moodle's JavaScript handling functions like $PAGE->requries->js_init_call().)

Since everything should work without JavaScript, load and initialising your scripts only after everything else on the page has loaded should not be a problem and will increase the perceived page-load performance for users.

===Minimise the number of .js files===

Try not to use too many different .js files. Each separate file that the browser has to load incurs an overhead.

On the other hand, organise the JavaScript logically to ease maintenance, and don't include large amounts of irrelevant JavaScript code. Code that is loaded but never used is a waste of time.

So, if you are writing a new module that needs its own JavaScript, try starting with a single file mod/mymod/module.js. If you find that you are writing a lot of JavaScript that is only needed when the teacher edits your module, but is not needed by students, then consider splitting that code into a separate file like mod/mymod/edit.js, and only including it where needed.

==How to achive these general principles in Moodle==

The rest of this page explains how you can achieve the above goals. Note that this particularly applies to loading and using the YUI 3 library which is Moodle 2.0's default. You should check which version of YUI Moodle is using as it may lag behind the latest YUI release (and, hence, the documentation).

===Getting Moodle to load your JavaScript files===

Everything required by the current page is tracked by the $PAGE->requires object, which is an instance of the [http://phpdocs.moodle.org/HEAD/moodlecore/page_requirements_manager.html page_requirements_manager] class defined in lib/outputrequirementslib.php.

The most important method in this class is the ->js_init_call(...) method. You use it like this:

<code php>
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'));
</code>

Note that this will implicitly load the JavaScript code in mod/mymod/module.js, and then call the M.mod_mymod.init_something function passing four string arguments 'some', 'data', 'from', 'PHP'. You can pass any PHP type as an argument. The PHP values are encoded with json_encode before being passed to JavaScript, so numbers, strings, arrays and objects all work.

Sometimes, the code in the JavaScript module mod/mymod/module.js may require some other JavaScript libraries to be loaded, or it may require some language strings. In that case you need to use the full form of js_init_call:

<code php>
$jsmodule = array(
'name' => 'mod_mymod',
'fullpath' => '/mod/mymod/module.js',
'requires' => array('base', 'io', 'node', 'json'),
'strings' => array(
array('something', 'mymod'),
array('confirmdelete', 'mymod'),
array('yes', 'moodle'),
array('no', 'moodle')
)
);
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'), false, $jsmodule);
</code>
(Naturally, it would be a good idea to put the definition of the $jsmodule array somewhere central like in the locallib.php file.)

The third (boolean) parameter is defined as "Wait for DOM Ready".

The libraries in the 'requires' sub-array are YUI3 (or YUI2) libraries. Moodle contains YUIs 'phploader' which understands what the library dependencies are, so this is all taken care of for you.

The strings are Moodle language strings. In order for Moodle to have correctly determined the user's language, you should only call js_init_call after the call to require_login, which sets the current course, and ensures the user is logged in.
Strings that are passed to Javascript in this way are then available from Javascript using M.util.get_string(), which works just like the PHP function.

$PAGE->requires keeps track of which files have been included. For example if two other modules both require the YUI base module, then it is only included once.

Your 'module.js' file in your plugin's directory will look something like this:

<code javascript>
M.mod_mymod = {};

M.mod_mymod.init = function(Y) {

// example to submit a form field on change
Y.on('change', function(e) {
Y.one('#mform1').submit();
}, '#id_fieldname' );
};
</code>

''mod_mymod'' needs changed to reflect the plugin type (e.g. mod,block,local,coursereport) and the name of your plugin throughout.

===JavaScript coding style===

Moodle JavaScript code should should follow the same [[Development:Coding_style|coding style as Moodle PHP code]], allowing for the differences between PHP and JavaScript.

For example, all the rules on ''function_names'', ''class_names'' and ''variablenames'' apply. You should document your code with [http://jsdoc.sourceforge.net/ JSDoc] comments. Layout your JavaScript expressions and statements like the equivalent PHP ones.

Normally, your .js files should simply define things like functions, classes and variables. When the file is loaded, no JavaScript code should actually be executed that has any effect unless it is the sort of code that can safely be executed once per HTML page. This is so that it plays nicely with the require_once-like behaviour of $PAGE->requires->js.

Do not pollute the global JavaScript name-space. Try to package your JavaScript into objects, and put all objects inside the global M object, like the M.mod_mymod example above.

===Different content when JavaScript is on or off===

Remember the overriding principals that everything should work with JavaScript off, and we should adopt a [[Progressive enhancement]] approach. However, there are valid reasons why sometimes you need different content with JavaScript is on or off. We can break it down into three cases:

====Content that should only be visible with JavaScript off====

An example of this is the automatic search when you are looking for a user to assign a role to. With JavaScript on, the search automatically starts after a delay. With JavaScript off, we want an explicit Search button visible.

To handle this case, Moodle automatically add a class 'jsenabled' to the body tag using JavaScript. So you just need to add a rule like
<code css>
body.jsenebled .mywidget .submitbutton {
display: none;
}
</code>
to the stylesheet, and the button will be invisible if JavaScript is enabled.

An alternative strategy is to remove the particular bits of HTML from the page using DOM methods. However, if your JavaScript is only loaded at the end of the page, it may take some time for the extra content to disappear, which leads to a disconcerting flicker in the page.

Yet another approach is the old-fashioned <noscript> tag.

====Content that needs to be visible right away when JavaScript is on====

An example is the <nowiki>[+] or [-]</nowiki> icon that can be used to expand/collapse each block if JavaScript is on.

We can divide this into two subcases:

=====Content generated by PHP code=====

Where the HTML for the JavaScript only widget is generated by PHP, we can make it invisible when JavaScript is off using just CSS:
<code css>
.mywidget {
display: none;
}
body.jsenabled .mywidget {
display: block;
}
</code>
However, it could be argued that this approach is not really progressive enhancement.

=====Content generated by JavaScript code=====

This is more in keeping with progressive enhancement, and this is the way that the expand/collapse block icon is handled.

We build the icon using DOM methods. The only problem is that as the JavaScript is loaded in the footer, there is a small delay before the icons appear. Since when the icons appear, they do not cause other content on the page to move around, that is OK. Also, this delayed appearance is becoming more common on the web. For example, on http://twitter.com/, some things only appear a moment after the main part of the page has finished loading.

However, it the delayed appearance is really a problem, then the only solution is to embed the JavaScript that generates the extra content in the middle of the HTML, using the js_writer class.

====Content that only appears when the user does something, when JavaScript is on====

An example of this is something like file picker dialog that appears when you add an image to some content in the HTML editor, or the one that pops up when you click 'Add new question' in the quiz editing interface.

We have the same two sub-cases:

=====Content generated by PHP code=====

In this case, you need to make sure the content is always covered by a ''display: none;'' rule in the CSS, but then when the user takes an action like clicking a button to reveal the extra content, you need to override that class name some how, perhaps by adding or removing a className using JavaScript.

=====Content generated by JavaScript code=====

In this case, there is no problem. When the use triggers the extra content to appear, it is constructed using DOM methods. There may be a tiny delay, but the chances are that it will hardly be noticeable to the human eye.

If the content generation may be slow (perhaps because it is waiting for an Ajax request) then you should display a progress icon. See, for example, the loading of the tooltip for help icons.

===Don't break XHTML strict!===

Remember that all Moodle output must be [[Development:XHTML|XHTML strict]], and that means that the HTML output must be well-formed XML. Inline JavaScript is a great way to break that. (JavaScript uses the < and & symbols that must be escaped in XML.) Therefore any JavaScript inline in the HTML should be escaped in a CDATA section:

<code xml>
<script type="text/javascript">
//<![CDATA[

// Your JavaScript code goes here.

//]]>
</script>
</code>

Of course, if you are following the above guidelines and putting most of your JavaScript in separate .js files, and using $PAGE->requires->js_init_call, then this is taken care of for you automatically.

==Testing==

JavaScript support varies a lot between browsers. JavaScript needs to be tested in IE, Firefox and Safari. Ideally, Moodle will support [http://developer.yahoo.com/yui/articles/gbs/ all the browsers that YUI does].

==See also==

* [[Development:Coding|The rest of Moodle coding guidelines]]
* [http://developer.yahoo.com/yui/ YUI documentation]
* [[Javascript FAQ]]
* [[Javascript and YUI 3 FAQ]]
* [[Development:Unobtrusive Javascript]]
* [[Development:JavaScript functions]]
* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]

[[Category:Coding guidelines|JavaScript guidelines]]
[[Category:Javascript|JavaScript guidelines]]
[[Category:AJAX|JavaScript guidelines]]

[[ja:開発:Javaスクリプトガイドライン]]

Development:JavaScript guidelines

2011-02-18T13:20:24Z

Howardsmiller: /* Getting Moodle to load your JavaScript files */

{{Moodle 2.0}}

These guidelines can only be applied fully from Moodle 2.0 onwards, because they rely on our new API to facilitate use of JavaScript.

When writing JavaScript for earlier versions of Moodle, please try to follow these guidelines in spirit and use the '''require_js''' function in place of $PAGE->requires->js_module/yui2_lib.

==General principles==

===Moodle should be usable without JavaScript===

Everything in Moodle should work with JavaScript turned off. This is important for accessibility, and in line with the principles of [[Development:Unobtrusive_Javascript|unobtrusive JavaScript]] and [[Development:Progressive_enhancement|progressive enhancement]].

===Minimise inline JavaScript===

Almost all JavaScript code should be in separate .js files. There should be the smallest possible amount of JavaScript inline in the HTML code of pages.

The only <script> tags in the HTML should be
# <script src=... tags to include the necessary .js files.
# Simple function calls to trigger initialisation and pass data from PHP to JavaScript. For example <script type="text/javascript">initialise_my_widget('some', 'data', 123);</script>.

Even these small amounts of JS you should not output directly. They will be generated automatically by calls to the $PAGE->requries->js_init_call() API. See below for details.

You should not use old-fashioned onXXX="event_handler" attributes in the HTML. Use Modern DOM events. The YUI events library makes this easy.

=== JavaScript libraries ===

* The official JavaScript library for Moodle is [[Development:YUI|YUI]]. That may not be your favourite, but it's the one that was chosen after careful research, so live with it.

* Moodle also has its own JavaScript library code, packaged into in various JavaScript modules.

* Moodle uses the '''TinyMCE''' HTML editor.

===When to include the JavaScript===

As per [http://developer.yahoo.com/performance/rules.html Yahoo's best practice guidelines], load and execute the JavaScript as late as possible, ideally the script tags should be the last thing before the </body> close tag. (This is the default behaviour with Moodle's JavaScript handling functions like $PAGE->requries->js_init_call().)

Since everything should work without JavaScript, load and initialising your scripts only after everything else on the page has loaded should not be a problem and will increase the perceived page-load performance for users.

===Minimise the number of .js files===

Try not to use too many different .js files. Each separate file that the browser has to load incurs an overhead.

On the other hand, organise the JavaScript logically to ease maintenance, and don't include large amounts of irrelevant JavaScript code. Code that is loaded but never used is a waste of time.

So, if you are writing a new module that needs its own JavaScript, try starting with a single file mod/mymod/module.js. If you find that you are writing a lot of JavaScript that is only needed when the teacher edits your module, but is not needed by students, then consider splitting that code into a separate file like mod/mymod/edit.js, and only including it where needed.

==How to achive these general principles in Moodle==

The rest of this page explains how you can achieve the above goals.

===Getting Moodle to load your JavaScript files===

Everything required by the current page is tracked by the $PAGE->requires object, which is an instance of the [http://phpdocs.moodle.org/HEAD/moodlecore/page_requirements_manager.html page_requirements_manager] class defined in lib/outputrequirementslib.php.

The most important method in this class is the ->js_init_call(...) method. You use it like this:

<code php>
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'));
</code>

Note that this will implicitly load the JavaScript code in mod/mymod/module.js, and then call the M.mod_mymod.init_something function passing four string arguments 'some', 'data', 'from', 'PHP'. You can pass any PHP type as an argument. The PHP values are encoded with json_encode before being passed to JavaScript, so numbers, strings, arrays and objects all work.

Sometimes, the code in the JavaScript module mod/mymod/module.js may require some other JavaScript libraries to be loaded, or it may require some language strings. In that case you need to use the full form of js_init_call:

<code php>
$jsmodule = array(
'name' => 'mod_mymod',
'fullpath' => '/mod/mymod/module.js',
'requires' => array('base', 'io', 'node', 'json'),
'strings' => array(
array('something', 'mymod'),
array('confirmdelete', 'mymod'),
array('yes', 'moodle'),
array('no', 'moodle')
)
);
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'), false, $jsmodule);
</code>
(Naturally, it would be a good idea to put the definition of the $jsmodule array somewhere central like in the locallib.php file.)

The third (boolean) parameter is defined as "Wait for DOM Ready".

The libraries in the 'requires' sub-array are YUI3 (or YUI2) libraries. Moodle contains YUIs 'phploader' which understands what the library dependencies are, so this is all taken care of for you.

The strings are Moodle language strings. In order for Moodle to have correctly determined the user's language, you should only call js_init_call after the call to require_login, which sets the current course, and ensures the user is logged in.
Strings that are passed to Javascript in this way are then available from Javascript using M.util.get_string(), which works just like the PHP function.

$PAGE->requires keeps track of which files have been included. For example if two other modules both require the YUI base module, then it is only included once.

Your 'module.js' file in your plugin's directory will look something like this:

<code javascript>
M.mod_mymod = {};

M.mod_mymod.init = function(Y) {

// example to submit a form field on change
Y.on('change', function(e) {
Y.one('#mform1').submit();
}, '#id_fieldname' );
};
</code>

''mod_mymod'' needs changed to reflect the plugin type (e.g. mod,block,local,coursereport) and the name of your plugin throughout.

===JavaScript coding style===

Moodle JavaScript code should should follow the same [[Development:Coding_style|coding style as Moodle PHP code]], allowing for the differences between PHP and JavaScript.

For example, all the rules on ''function_names'', ''class_names'' and ''variablenames'' apply. You should document your code with [http://jsdoc.sourceforge.net/ JSDoc] comments. Layout your JavaScript expressions and statements like the equivalent PHP ones.

Normally, your .js files should simply define things like functions, classes and variables. When the file is loaded, no JavaScript code should actually be executed that has any effect unless it is the sort of code that can safely be executed once per HTML page. This is so that it plays nicely with the require_once-like behaviour of $PAGE->requires->js.

Do not pollute the global JavaScript name-space. Try to package your JavaScript into objects, and put all objects inside the global M object, like the M.mod_mymod example above.

===Different content when JavaScript is on or off===

Remember the overriding principals that everything should work with JavaScript off, and we should adopt a [[Progressive enhancement]] approach. However, there are valid reasons why sometimes you need different content with JavaScript is on or off. We can break it down into three cases:

====Content that should only be visible with JavaScript off====

An example of this is the automatic search when you are looking for a user to assign a role to. With JavaScript on, the search automatically starts after a delay. With JavaScript off, we want an explicit Search button visible.

To handle this case, Moodle automatically add a class 'jsenabled' to the body tag using JavaScript. So you just need to add a rule like
<code css>
body.jsenebled .mywidget .submitbutton {
display: none;
}
</code>
to the stylesheet, and the button will be invisible if JavaScript is enabled.

An alternative strategy is to remove the particular bits of HTML from the page using DOM methods. However, if your JavaScript is only loaded at the end of the page, it may take some time for the extra content to disappear, which leads to a disconcerting flicker in the page.

Yet another approach is the old-fashioned <noscript> tag.

====Content that needs to be visible right away when JavaScript is on====

An example is the <nowiki>[+] or [-]</nowiki> icon that can be used to expand/collapse each block if JavaScript is on.

We can divide this into two subcases:

=====Content generated by PHP code=====

Where the HTML for the JavaScript only widget is generated by PHP, we can make it invisible when JavaScript is off using just CSS:
<code css>
.mywidget {
display: none;
}
body.jsenabled .mywidget {
display: block;
}
</code>
However, it could be argued that this approach is not really progressive enhancement.

=====Content generated by JavaScript code=====

This is more in keeping with progressive enhancement, and this is the way that the expand/collapse block icon is handled.

We build the icon using DOM methods. The only problem is that as the JavaScript is loaded in the footer, there is a small delay before the icons appear. Since when the icons appear, they do not cause other content on the page to move around, that is OK. Also, this delayed appearance is becoming more common on the web. For example, on http://twitter.com/, some things only appear a moment after the main part of the page has finished loading.

However, it the delayed appearance is really a problem, then the only solution is to embed the JavaScript that generates the extra content in the middle of the HTML, using the js_writer class.

====Content that only appears when the user does something, when JavaScript is on====

An example of this is something like file picker dialog that appears when you add an image to some content in the HTML editor, or the one that pops up when you click 'Add new question' in the quiz editing interface.

We have the same two sub-cases:

=====Content generated by PHP code=====

In this case, you need to make sure the content is always covered by a ''display: none;'' rule in the CSS, but then when the user takes an action like clicking a button to reveal the extra content, you need to override that class name some how, perhaps by adding or removing a className using JavaScript.

=====Content generated by JavaScript code=====

In this case, there is no problem. When the use triggers the extra content to appear, it is constructed using DOM methods. There may be a tiny delay, but the chances are that it will hardly be noticeable to the human eye.

If the content generation may be slow (perhaps because it is waiting for an Ajax request) then you should display a progress icon. See, for example, the loading of the tooltip for help icons.

===Don't break XHTML strict!===

Remember that all Moodle output must be [[Development:XHTML|XHTML strict]], and that means that the HTML output must be well-formed XML. Inline JavaScript is a great way to break that. (JavaScript uses the < and & symbols that must be escaped in XML.) Therefore any JavaScript inline in the HTML should be escaped in a CDATA section:

<code xml>
<script type="text/javascript">
//<![CDATA[

// Your JavaScript code goes here.

//]]>
</script>
</code>

Of course, if you are following the above guidelines and putting most of your JavaScript in separate .js files, and using $PAGE->requires->js_init_call, then this is taken care of for you automatically.

==Testing==

JavaScript support varies a lot between browsers. JavaScript needs to be tested in IE, Firefox and Safari. Ideally, Moodle will support [http://developer.yahoo.com/yui/articles/gbs/ all the browsers that YUI does].

==See also==

* [[Development:Coding|The rest of Moodle coding guidelines]]
* [http://developer.yahoo.com/yui/ YUI documentation]
* [[Javascript FAQ]]
* [[Javascript and YUI 3 FAQ]]
* [[Development:Unobtrusive Javascript]]
* [[Development:JavaScript functions]]
* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]

[[Category:Coding guidelines|JavaScript guidelines]]
[[Category:Javascript|JavaScript guidelines]]
[[Category:AJAX|JavaScript guidelines]]

[[ja:開発:Javaスクリプトガイドライン]]

Development:JavaScript guidelines

2011-02-18T13:16:26Z

Howardsmiller: /* Getting Moodle to load your JavaScript files */

{{Moodle 2.0}}

These guidelines can only be applied fully from Moodle 2.0 onwards, because they rely on our new API to facilitate use of JavaScript.

When writing JavaScript for earlier versions of Moodle, please try to follow these guidelines in spirit and use the '''require_js''' function in place of $PAGE->requires->js_module/yui2_lib.

==General principles==

===Moodle should be usable without JavaScript===

Everything in Moodle should work with JavaScript turned off. This is important for accessibility, and in line with the principles of [[Development:Unobtrusive_Javascript|unobtrusive JavaScript]] and [[Development:Progressive_enhancement|progressive enhancement]].

===Minimise inline JavaScript===

Almost all JavaScript code should be in separate .js files. There should be the smallest possible amount of JavaScript inline in the HTML code of pages.

The only <script> tags in the HTML should be
# <script src=... tags to include the necessary .js files.
# Simple function calls to trigger initialisation and pass data from PHP to JavaScript. For example <script type="text/javascript">initialise_my_widget('some', 'data', 123);</script>.

Even these small amounts of JS you should not output directly. They will be generated automatically by calls to the $PAGE->requries->js_init_call() API. See below for details.

You should not use old-fashioned onXXX="event_handler" attributes in the HTML. Use Modern DOM events. The YUI events library makes this easy.

=== JavaScript libraries ===

* The official JavaScript library for Moodle is [[Development:YUI|YUI]]. That may not be your favourite, but it's the one that was chosen after careful research, so live with it.

* Moodle also has its own JavaScript library code, packaged into in various JavaScript modules.

* Moodle uses the '''TinyMCE''' HTML editor.

===When to include the JavaScript===

As per [http://developer.yahoo.com/performance/rules.html Yahoo's best practice guidelines], load and execute the JavaScript as late as possible, ideally the script tags should be the last thing before the </body> close tag. (This is the default behaviour with Moodle's JavaScript handling functions like $PAGE->requries->js_init_call().)

Since everything should work without JavaScript, load and initialising your scripts only after everything else on the page has loaded should not be a problem and will increase the perceived page-load performance for users.

===Minimise the number of .js files===

Try not to use too many different .js files. Each separate file that the browser has to load incurs an overhead.

On the other hand, organise the JavaScript logically to ease maintenance, and don't include large amounts of irrelevant JavaScript code. Code that is loaded but never used is a waste of time.

So, if you are writing a new module that needs its own JavaScript, try starting with a single file mod/mymod/module.js. If you find that you are writing a lot of JavaScript that is only needed when the teacher edits your module, but is not needed by students, then consider splitting that code into a separate file like mod/mymod/edit.js, and only including it where needed.

==How to achive these general principles in Moodle==

The rest of this page explains how you can achieve the above goals.

===Getting Moodle to load your JavaScript files===

Everything required by the current page is tracked by the $PAGE->requires object, which is an instance of the [http://phpdocs.moodle.org/HEAD/moodlecore/page_requirements_manager.html page_requirements_manager] class defined in lib/outputrequirementslib.php.

The most important method in this class is the ->js_init_call(...) method. You use it like this:

<code php>
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'));
</code>

Note that this will implicitly load the JavaScript code in mod/mymod/module.js, and then call the M.mod_mymod.init_something function passing four string arguments 'some', 'data', 'from', 'PHP'. You can pass any PHP type as an argument. The PHP values are encoded with json_encode before being passed to JavaScript, so numbers, strings, arrays and objects all work.

Sometimes, the code in the JavaScript module mod/mymod/module.js may require some other JavaScript libraries to be loaded, or it may require some language strings. In that case you need to use the full form of js_init_call:

<code php>
$jsmodule = array(
'name' => 'mod_mymod',
'fullpath' => '/mod/mymod/module.js',
'requires' => array('base', 'io', 'node', 'json'),
'strings' => array(
array('something', 'mymod'),
array('confirmdelete', 'mymod'),
array('yes', 'moodle'),
array('no', 'moodle')
)
);
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'), false, $jsmodule);
</code>
(Naturally, it would be a good idea to put the definition of the $jsmodule array somewhere central like in the locallib.php file.)

The third (boolean) parameter is defined as "Wait for DOM Ready".

The libraries in the 'requires' sub-array are YUI3 (or YUI2) libraries. Moodle contains YUIs 'phploader' which understands what the library dependencies are, so this is all taken care of for you.

The strings are Moodle language strings. In order for Moodle to have correctly determined the user's language, you should only call js_init_call after the call to require_login, which sets the current course, and ensures the user is logged in.
Strings that are passed to Javascript in this way are then available from Javascript using M.util.get_string(), which works just like the PHP function.

$PAGE->requires keeps track of which files have been included. For example if two other modules both require the YUI base module, then it is only included once.

===JavaScript coding style===

Moodle JavaScript code should should follow the same [[Development:Coding_style|coding style as Moodle PHP code]], allowing for the differences between PHP and JavaScript.

For example, all the rules on ''function_names'', ''class_names'' and ''variablenames'' apply. You should document your code with [http://jsdoc.sourceforge.net/ JSDoc] comments. Layout your JavaScript expressions and statements like the equivalent PHP ones.

Normally, your .js files should simply define things like functions, classes and variables. When the file is loaded, no JavaScript code should actually be executed that has any effect unless it is the sort of code that can safely be executed once per HTML page. This is so that it plays nicely with the require_once-like behaviour of $PAGE->requires->js.

Do not pollute the global JavaScript name-space. Try to package your JavaScript into objects, and put all objects inside the global M object, like the M.mod_mymod example above.

===Different content when JavaScript is on or off===

Remember the overriding principals that everything should work with JavaScript off, and we should adopt a [[Progressive enhancement]] approach. However, there are valid reasons why sometimes you need different content with JavaScript is on or off. We can break it down into three cases:

====Content that should only be visible with JavaScript off====

An example of this is the automatic search when you are looking for a user to assign a role to. With JavaScript on, the search automatically starts after a delay. With JavaScript off, we want an explicit Search button visible.

To handle this case, Moodle automatically add a class 'jsenabled' to the body tag using JavaScript. So you just need to add a rule like
<code css>
body.jsenebled .mywidget .submitbutton {
display: none;
}
</code>
to the stylesheet, and the button will be invisible if JavaScript is enabled.

An alternative strategy is to remove the particular bits of HTML from the page using DOM methods. However, if your JavaScript is only loaded at the end of the page, it may take some time for the extra content to disappear, which leads to a disconcerting flicker in the page.

Yet another approach is the old-fashioned <noscript> tag.

====Content that needs to be visible right away when JavaScript is on====

An example is the <nowiki>[+] or [-]</nowiki> icon that can be used to expand/collapse each block if JavaScript is on.

We can divide this into two subcases:

=====Content generated by PHP code=====

Where the HTML for the JavaScript only widget is generated by PHP, we can make it invisible when JavaScript is off using just CSS:
<code css>
.mywidget {
display: none;
}
body.jsenabled .mywidget {
display: block;
}
</code>
However, it could be argued that this approach is not really progressive enhancement.

=====Content generated by JavaScript code=====

This is more in keeping with progressive enhancement, and this is the way that the expand/collapse block icon is handled.

We build the icon using DOM methods. The only problem is that as the JavaScript is loaded in the footer, there is a small delay before the icons appear. Since when the icons appear, they do not cause other content on the page to move around, that is OK. Also, this delayed appearance is becoming more common on the web. For example, on http://twitter.com/, some things only appear a moment after the main part of the page has finished loading.

However, it the delayed appearance is really a problem, then the only solution is to embed the JavaScript that generates the extra content in the middle of the HTML, using the js_writer class.

====Content that only appears when the user does something, when JavaScript is on====

An example of this is something like file picker dialog that appears when you add an image to some content in the HTML editor, or the one that pops up when you click 'Add new question' in the quiz editing interface.

We have the same two sub-cases:

=====Content generated by PHP code=====

In this case, you need to make sure the content is always covered by a ''display: none;'' rule in the CSS, but then when the user takes an action like clicking a button to reveal the extra content, you need to override that class name some how, perhaps by adding or removing a className using JavaScript.

=====Content generated by JavaScript code=====

In this case, there is no problem. When the use triggers the extra content to appear, it is constructed using DOM methods. There may be a tiny delay, but the chances are that it will hardly be noticeable to the human eye.

If the content generation may be slow (perhaps because it is waiting for an Ajax request) then you should display a progress icon. See, for example, the loading of the tooltip for help icons.

===Don't break XHTML strict!===

Remember that all Moodle output must be [[Development:XHTML|XHTML strict]], and that means that the HTML output must be well-formed XML. Inline JavaScript is a great way to break that. (JavaScript uses the < and & symbols that must be escaped in XML.) Therefore any JavaScript inline in the HTML should be escaped in a CDATA section:

<code xml>
<script type="text/javascript">
//<![CDATA[

// Your JavaScript code goes here.

//]]>
</script>
</code>

Of course, if you are following the above guidelines and putting most of your JavaScript in separate .js files, and using $PAGE->requires->js_init_call, then this is taken care of for you automatically.

==Testing==

JavaScript support varies a lot between browsers. JavaScript needs to be tested in IE, Firefox and Safari. Ideally, Moodle will support [http://developer.yahoo.com/yui/articles/gbs/ all the browsers that YUI does].

==See also==

* [[Development:Coding|The rest of Moodle coding guidelines]]
* [http://developer.yahoo.com/yui/ YUI documentation]
* [[Javascript FAQ]]
* [[Javascript and YUI 3 FAQ]]
* [[Development:Unobtrusive Javascript]]
* [[Development:JavaScript functions]]
* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]

[[Category:Coding guidelines|JavaScript guidelines]]
[[Category:Javascript|JavaScript guidelines]]
[[Category:AJAX|JavaScript guidelines]]

[[ja:開発:Javaスクリプトガイドライン]]

Javascript and YUI 3 FAQ

2011-02-09T14:07:03Z

Howardsmiller: /* How does Y relate to the yui docs? To step back, how do I work out what methods etc. Y has that I can use? */

{{Moodle 2.0}}A quick primer on the internals of Moodle's javascript, and how to use YUI within it. Based on [http://moodle.org/mod/forum/discuss.php?d=168157 formlibs plus ajax] discussion in the General Developer forum.

== How do I add an event to make changing a value in a select control submit its parent form? ==

When you put the field's name in addElement, it automatically gives it an ID. Say you called it "select1", the id would be "id_select1". There's an exception to this (I can't remember which element it is) in which case you'll need to define an id in the attributes.

You'll then want to get the select and the form using YUI, and attach an event listener:

<code javascript>Y.on('change', submit_form, '#select1');
function submit_form() {
var form = Y.one('#mform1'); // The id for the moodle form is automatically set.
var form.submit();
}</code>

This code would normally live in a file called 'module.js' within your plugin directory. See other FAQs for actually accessing this.

Explanation:
* The first line sets up the event listener. The first parameter says watch for a 'change' of value. The second is the name of the callback function to execute when the change happens. The third is the name of the DOM element that is being watched (in this case the select form element with id='select1'. The second parameter matches the name of the callback function below.
* For a full explanation of event listeners see http://developer.yahoo.com/yui/3/event/
* The callback function 'submit_form' uses YUI's methods to access the form in which the select box lives (in this case with id="form1") and then submits it. For a full explanation of the Y.one method see http://developer.yahoo.com/yui/3/node
* When the form node has been obtained, the node's submit method is used to submit the form. See the API documentation for YUI's node class for this and other node methods - http://developer.yahoo.com/yui/3/api/Node.html

== How do I get that into the page. Is that a 'yui' call or a 'requires_js" call or whatever? ==

The best documentation to read is here: [[Development:JavaScript_guidelines]]

Essentially, you need to define M.your_plugin as an object in a javascript file. You then define the submit_form() function as a method of M.your_plugin, and put the Y.on() call in the init method of the object. You then include the javascript file with $PAGE->requires_js() and call the init method with js_init_call (see docs).

== Also, where does the 'Y' get defined? Is this documented somewhere (I can't find anything)? ==

Y is a bit complicated, it took me a while to really understand what happens, but here's a brief explanation:

Y is a namespace generated when YUI is initialised containing the methods from all the loaded modules. Internally, moodle initialises Y and passes it to the module's init function in js_init_call, as the first parameter. To access Y from your init function, you need to do this:

<code javascript>M.my_plugin.init = function(Y) { //Y is now accessible in the scope of init().</code>
However, you probably want access Y in your object's other method's too, so you need to do something like this:

<code javascript>M.my_plugin.init = function(Y) { //Y is now accessible in the scope of init().
this.Y = Y; // this.Y is now accessible from all methods of M.my_plugin
}</code>
For tidiness, I always start any other method using Y with "var Y = this.Y" so I don't have to keep prefixing with this.

You may also find this page useful (or more confusing ) [[Development:How_to_create_a_YUI_3_module]]

== The M.your_plugin thing. What if it isn't a module? What if it's a report somewhere or a local plugin. What's the syntax for this thing? I guess the 'M' is just an arbitrary "thing" ==

First of all, disambiguation of terms:

* A ''YUI Module'' is subset of YUI functionality, contained in it's own namespace, e.g Y.Node
* A ''Moodle Module'', I'm sure you understand.
* A ''Javascript Module'' in this context, is a subset of javascript functionality contained in it's own M. namespace.
Any Moodle plugin can define it's own Javascript Module, whether it's a Moodle Module or a different type of plugin. Usually this will be in the plugin's module.js file, and be called M.plugintype_pluginame (similar to the lang file naming convention), but the object passed as the 4th parameter of $PAGE->requires->js_init_call() allows you to customise this.

A good example of Y's usage that I can point you to is my quickfindlist block.

Take a look at the bottom of get_content() in [https://github.com/marxjohnson/moodle-block_quickfindlist/blob/dev/block_quickfindlist.php block_quickfindlist.php]. This defines $jsmodule (the Javascript module's parameters, including the name, the file it's stored in, and the YUI modules it needs), $jsdata (extra parameters to pass with the init call, in addition to Y), and then passes them, along with the name of the module's init function, to js_init_call(). Note that as it's a block, it uses $this->page in place of $PAGE.

Now look at [https://github.com/marxjohnson/moodle-block_quickfindlist/blob/dev/module.js module.js]. It defines M.block_quickfindlist (which is the module we specified with $jsmodule) and the init() method (which we referenced in js_init_call()). init accepts 6 parameters: Y, and the 5 set in $jsdata. It then stores a copy of Y in M.block_quickfindlist.Y so it can be used in other methods, and uses Y itself to call Y.on(), adding event listeners to the block.
M.block_quickfindlist.search() is defined futher down module.js - it needs acces to Y too, so we create a copy in the method's scope for easy referencing, before using it to make an AJAX request with Y.io(). You can also see use of M.cfg, another Javascript Module, to access the value of wwwroot.

An important thing to note about Y being used all over the place is that as I understand it, Y is only initialised once with all the YUI Modules required by any Javascript Modules on the current page (hence the requirements manager). It's then passed to each module's init function, so they can use it in their own scope.

The actual "core" javascript code to do this would look something like:

<code javascript>
YUI.use('required', 'yui', 'modules', function(Y) {
// YUI.use initialises Y with required modules,
// and passes it to an anonymous function.
// Y is then available to pass to our own init functions
M.block_blockname.init_function(Y);
M.report_reportname.init_function(Y, other, parameters);
});
</code>

== How does Y relate to the yui docs? To step back, how do I work out what methods etc. Y has that I can use? ==

When you request a module for inclusion, it's classes will be attached to the Y namespace. You can see it's classes by going to the YUI documentation for that module, and looking at the API docs. Each module's classes then has a set of properties and methods.

For example the IO module contains the io class. So telling Moodle that your javascript module requires io will give you access to Y.io and all of its methods.
In general, reading the YUI module's documentation and it's examples will give you a good general idea of how to use it's functionality.

It's also worth noting that some modules will create a shortcut method attached directly to Y for convenience. For instance Y.io.io() can also be called using Y.io(), and Y.Node.one() can be called using Y.one().

I'm guessing that some YUI modules are loaded by default ('base' and 'node' probably are), but the requirements manager should make sure that each one's only loaded once. I always define all the YUI Modules my Javascript Module needs, just to make sure.

== It doesn't work. Now what? ==

Firstly, make sure you have debugging on your site set to Developer (and messages displayed). Without this level of debugging any detected errors will fail silently.

==See also==

* [http://developer.yahoo.com/yui/3/ YUI documentation]
* [[Javascript FAQ]]

[[Category:Developer]]
[[Category:Javascript]]

Javascript and YUI 3 FAQ

2011-02-09T11:08:33Z

Howardsmiller: /* How do I add an event to make changing a value in a select control submit its parent form? */

{{Moodle 2.0}}A quick primer on the internals of Moodle's javascript, and how to use YUI within it. Based on [http://moodle.org/mod/forum/discuss.php?d=168157 formlibs plus ajax] discussion in the General Developer forum.

== How do I add an event to make changing a value in a select control submit its parent form? ==

When you put the field's name in addElement, it automatically gives it an ID. Say you called it "select1", the id would be "id_select1". There's an exception to this (I can't remember which element it is) in which case you'll need to define an id in the attributes.

You'll then want to get the select and the form using YUI, and attach an event listener:

<code javascript>Y.on('change', submit_form, '#select1');
function submit_form() {
var form = Y.one('#mform1'); // The id for the moodle form is automatically set.
var form.submit();
}</code>

This code would normally live in a file called 'module.js' within your plugin directory. See other FAQs for actually accessing this.

Explanation:
* The first line sets up the event listener. The first parameter says watch for a 'change' of value. The second is the name of the callback function to execute when the change happens. The third is the name of the DOM element that is being watched (in this case the select form element with id='select1'. The second parameter matches the name of the callback function below.
* For a full explanation of event listeners see http://developer.yahoo.com/yui/3/event/
* The callback function 'submit_form' uses YUI's methods to access the form in which the select box lives (in this case with id="form1") and then submits it. For a full explanation of the Y.one method see http://developer.yahoo.com/yui/3/node
* When the form node has been obtained, the node's submit method is used to submit the form. See the API documentation for YUI's node class for this and other node methods - http://developer.yahoo.com/yui/3/api/Node.html

== How do I get that into the page. Is that a 'yui' call or a 'requires_js" call or whatever? ==

The best documentation to read is here: [[Development:JavaScript_guidelines]]

Essentially, you need to define M.your_plugin as an object in a javascript file. You then define the submit_form() function as a method of M.your_plugin, and put the Y.on() call in the init method of the object. You then include the javascript file with $PAGE->requires_js() and call the init method with js_init_call (see docs).

== Also, where does the 'Y' get defined? Is this documented somewhere (I can't find anything)? ==

Y is a bit complicated, it took me a while to really understand what happens, but here's a brief explanation:

Y is a namespace generated when YUI is initialised containing the methods from all the loaded modules. Internally, moodle initialises Y and passes it to the module's init function in js_init_call, as the first parameter. To access Y from your init function, you need to do this:

<code javascript>M.my_plugin.init = function(Y) { //Y is now accessible in the scope of init().</code>
However, you probably want access Y in your object's other method's too, so you need to do something like this:

<code javascript>M.my_plugin.init = function(Y) { //Y is now accessible in the scope of init().
this.Y = Y; // this.Y is now accessible from all methods of M.my_plugin
}</code>
For tidiness, I always start any other method using Y with "var Y = this.Y" so I don't have to keep prefixing with this.

You may also find this page useful (or more confusing ) [[Development:How_to_create_a_YUI_3_module]]

== The M.your_plugin thing. What if it isn't a module? What if it's a report somewhere or a local plugin. What's the syntax for this thing? I guess the 'M' is just an arbitrary "thing" ==

First of all, disambiguation of terms:

* A ''YUI Module'' is subset of YUI functionality, contained in it's own namespace, e.g Y.Node
* A ''Moodle Module'', I'm sure you understand.
* A ''Javascript Module'' in this context, is a subset of javascript functionality contained in it's own M. namespace.
Any Moodle plugin can define it's own Javascript Module, whether it's a Moodle Module or a different type of plugin. Usually this will be in the plugin's module.js file, and be called M.plugintype_pluginame (similar to the lang file naming convention), but the object passed as the 4th parameter of $PAGE->requires->js_init_call() allows you to customise this.

A good example of Y's usage that I can point you to is my quickfindlist block.

Take a look at the bottom of get_content() in [https://github.com/marxjohnson/moodle-block_quickfindlist/blob/dev/block_quickfindlist.php block_quickfindlist.php]. This defines $jsmodule (the Javascript module's parameters, including the name, the file it's stored in, and the YUI modules it needs), $jsdata (extra parameters to pass with the init call, in addition to Y), and then passes them, along with the name of the module's init function, to js_init_call(). Note that as it's a block, it uses $this->page in place of $PAGE.

Now look at [https://github.com/marxjohnson/moodle-block_quickfindlist/blob/dev/module.js module.js]. It defines M.block_quickfindlist (which is the module we specified with $jsmodule) and the init() method (which we referenced in js_init_call()). init accepts 6 parameters: Y, and the 5 set in $jsdata. It then stores a copy of Y in M.block_quickfindlist.Y so it can be used in other methods, and uses Y itself to call Y.on(), adding event listeners to the block.
M.block_quickfindlist.search() is defined futher down module.js - it needs acces to Y too, so we create a copy in the method's scope for easy referencing, before using it to make an AJAX request with Y.io(). You can also see use of M.cfg, another Javascript Module, to access the value of wwwroot.

An important thing to note about Y being used all over the place is that as I understand it, Y is only initialised once with all the YUI Modules required by any Javascript Modules on the current page (hence the requirements manager). It's then passed to each module's init function, so they can use it in their own scope.

The actual "core" javascript code to do this would look something like:

<code javascript>
YUI.use('required', 'yui', 'modules', function(Y) {
// YUI.use initialises Y with required modules,
// and passes it to an anonymous function.
// Y is then available to pass to our own init functions
M.block_blockname.init_function(Y);
M.report_reportname.init_function(Y, other, parameters);
});
</code>

== How does Y relate to the yui docs? To step back, how do I work out what methods etc. Y has that I can use? ==

When you request a module for inclusion, it's classes will be attached to the Y namespace. You can see it's classes by going to the YUI documentation for that module, and looking at the API docs. Each module's classes then has a set of properties and methods.

For example the IO module contains the io class. So telling Moodle that your javascript module requires io will give you access to Y.io and all of its methods.
In general, reading the YUI module's documentation and it's examples will give you a good general idea of how to use it's functionality.

It's also worth noting that some modules will create a shortcut method attached directly to Y for convenience. For instance Y.io.io() can also be called using Y.io(), and Y.Node.one() can be called using Y.one().

I'm guessing that some YUI modules are loaded by default ('base' and 'node' probably are), but the requirements manager should make sure that each one's only loaded once. I always define all the YUI Modules my Javascript Module needs, just to make sure.

==See also==

* [http://developer.yahoo.com/yui/3/ YUI documentation]
* [[Javascript FAQ]]

[[Category:Developer]]
[[Category:Javascript]]

Javascript and YUI 3 FAQ

2011-02-09T11:07:22Z

Howardsmiller: /* How do I add an event to make changing a value in a select control submit its parent form? */

{{Moodle 2.0}}A quick primer on the internals of Moodle's javascript, and how to use YUI within it. Based on [http://moodle.org/mod/forum/discuss.php?d=168157 formlibs plus ajax] discussion in the General Developer forum.

== How do I add an event to make changing a value in a select control submit its parent form? ==

When you put the field's name in addElement, it automatically gives it an ID. Say you called it "select1", the id would be "id_select1". There's an exception to this (I can't remember which element it is) in which case you'll need to define an id in the attributes.

You'll then want to get the select and the form using YUI, and attach an event listener:

<code javascript>Y.on('change', submit_form, '#select1');
function submit_form() {
var form = Y.one('#mform1'); // The id for the moodle form is automatically set.
var form.submit();
}</code>

Explanation:
* The first line sets up the event listener. The first parameter says watch for a 'change' of value. The second is the name of the callback function to execute when the change happens. The third is the name of the DOM element that is being watched (in this case the select form element with id='select1'. The second parameter matches the name of the callback function below.
* For a full explanation of event listeners see http://developer.yahoo.com/yui/3/event/
* The callback function 'submit_form' uses YUI's methods to access the form in which the select box lives (in this case with id="form1") and then submits it. For a full explanation of the Y.one method see http://developer.yahoo.com/yui/3/node
* When the form node has been obtained, the node's submit method is used to submit the form. See the API documentation for YUI's node class for this and other node methods - http://developer.yahoo.com/yui/3/api/Node.html

== How do I get that into the page. Is that a 'yui' call or a 'requires_js" call or whatever? ==

The best documentation to read is here: [[Development:JavaScript_guidelines]]

Essentially, you need to define M.your_plugin as an object in a javascript file. You then define the submit_form() function as a method of M.your_plugin, and put the Y.on() call in the init method of the object. You then include the javascript file with $PAGE->requires_js() and call the init method with js_init_call (see docs).

== Also, where does the 'Y' get defined? Is this documented somewhere (I can't find anything)? ==

Y is a bit complicated, it took me a while to really understand what happens, but here's a brief explanation:

Y is a namespace generated when YUI is initialised containing the methods from all the loaded modules. Internally, moodle initialises Y and passes it to the module's init function in js_init_call, as the first parameter. To access Y from your init function, you need to do this:

<code javascript>M.my_plugin.init = function(Y) { //Y is now accessible in the scope of init().</code>
However, you probably want access Y in your object's other method's too, so you need to do something like this:

<code javascript>M.my_plugin.init = function(Y) { //Y is now accessible in the scope of init().
this.Y = Y; // this.Y is now accessible from all methods of M.my_plugin
}</code>
For tidiness, I always start any other method using Y with "var Y = this.Y" so I don't have to keep prefixing with this.

You may also find this page useful (or more confusing ) [[Development:How_to_create_a_YUI_3_module]]

== The M.your_plugin thing. What if it isn't a module? What if it's a report somewhere or a local plugin. What's the syntax for this thing? I guess the 'M' is just an arbitrary "thing" ==

First of all, disambiguation of terms:

* A ''YUI Module'' is subset of YUI functionality, contained in it's own namespace, e.g Y.Node
* A ''Moodle Module'', I'm sure you understand.
* A ''Javascript Module'' in this context, is a subset of javascript functionality contained in it's own M. namespace.
Any Moodle plugin can define it's own Javascript Module, whether it's a Moodle Module or a different type of plugin. Usually this will be in the plugin's module.js file, and be called M.plugintype_pluginame (similar to the lang file naming convention), but the object passed as the 4th parameter of $PAGE->requires->js_init_call() allows you to customise this.

A good example of Y's usage that I can point you to is my quickfindlist block.

Take a look at the bottom of get_content() in [https://github.com/marxjohnson/moodle-block_quickfindlist/blob/dev/block_quickfindlist.php block_quickfindlist.php]. This defines $jsmodule (the Javascript module's parameters, including the name, the file it's stored in, and the YUI modules it needs), $jsdata (extra parameters to pass with the init call, in addition to Y), and then passes them, along with the name of the module's init function, to js_init_call(). Note that as it's a block, it uses $this->page in place of $PAGE.

Now look at [https://github.com/marxjohnson/moodle-block_quickfindlist/blob/dev/module.js module.js]. It defines M.block_quickfindlist (which is the module we specified with $jsmodule) and the init() method (which we referenced in js_init_call()). init accepts 6 parameters: Y, and the 5 set in $jsdata. It then stores a copy of Y in M.block_quickfindlist.Y so it can be used in other methods, and uses Y itself to call Y.on(), adding event listeners to the block.
M.block_quickfindlist.search() is defined futher down module.js - it needs acces to Y too, so we create a copy in the method's scope for easy referencing, before using it to make an AJAX request with Y.io(). You can also see use of M.cfg, another Javascript Module, to access the value of wwwroot.

An important thing to note about Y being used all over the place is that as I understand it, Y is only initialised once with all the YUI Modules required by any Javascript Modules on the current page (hence the requirements manager). It's then passed to each module's init function, so they can use it in their own scope.

The actual "core" javascript code to do this would look something like:

<code javascript>
YUI.use('required', 'yui', 'modules', function(Y) {
// YUI.use initialises Y with required modules,
// and passes it to an anonymous function.
// Y is then available to pass to our own init functions
M.block_blockname.init_function(Y);
M.report_reportname.init_function(Y, other, parameters);
});
</code>

== How does Y relate to the yui docs? To step back, how do I work out what methods etc. Y has that I can use? ==

When you request a module for inclusion, it's classes will be attached to the Y namespace. You can see it's classes by going to the YUI documentation for that module, and looking at the API docs. Each module's classes then has a set of properties and methods.

For example the IO module contains the io class. So telling Moodle that your javascript module requires io will give you access to Y.io and all of its methods.
In general, reading the YUI module's documentation and it's examples will give you a good general idea of how to use it's functionality.

It's also worth noting that some modules will create a shortcut method attached directly to Y for convenience. For instance Y.io.io() can also be called using Y.io(), and Y.Node.one() can be called using Y.one().

I'm guessing that some YUI modules are loaded by default ('base' and 'node' probably are), but the requirements manager should make sure that each one's only loaded once. I always define all the YUI Modules my Javascript Module needs, just to make sure.

==See also==

* [http://developer.yahoo.com/yui/3/ YUI documentation]
* [[Javascript FAQ]]

[[Category:Developer]]
[[Category:Javascript]]

Javascript and YUI 3 FAQ

2011-02-09T11:03:49Z

Howardsmiller: /* How do I add an event to make changing a value in a select control submit its parent form? */

{{Moodle 2.0}}A quick primer on the internals of Moodle's javascript, and how to use YUI within it. Based on [http://moodle.org/mod/forum/discuss.php?d=168157 formlibs plus ajax] discussion in the General Developer forum.

== How do I add an event to make changing a value in a select control submit its parent form? ==

When you put the field's name in addElement, it automatically gives it an ID. Say you called it "select1", the id would be "id_select1". There's an exception to this (I can't remember which element it is) in which case you'll need to define an id in the attributes.

You'll then want to get the select and the form using YUI, and attach an event listener:

<code javascript>Y.on('change', submit_form, '#select1');
function submit_form() {
var form = Y.one('#mform1'); // The id for the moodle form is automatically set.
var form.submit();
}</code>

Explanation:
* The first line sets up the event listener. The first parameter says watch for a 'change' of value. The second is the name of the callback function to execute when the change happens. The third is the name of the DOM element that is being watched (in this case the select form element with id='select1'. The second parameter matches the name of the callback function below.
* For a full explanation of event listeners see http://developer.yahoo.com/yui/3/event/
* The callback function 'submit_form' uses YUI's methods to access the form in which the select box lives (in this case with id="form1") and then submits it. For a full explanation of the Y.one method see http://developer.yahoo.com/yui/3/node

== How do I get that into the page. Is that a 'yui' call or a 'requires_js" call or whatever? ==

The best documentation to read is here: [[Development:JavaScript_guidelines]]

Essentially, you need to define M.your_plugin as an object in a javascript file. You then define the submit_form() function as a method of M.your_plugin, and put the Y.on() call in the init method of the object. You then include the javascript file with $PAGE->requires_js() and call the init method with js_init_call (see docs).

== Also, where does the 'Y' get defined? Is this documented somewhere (I can't find anything)? ==

Y is a bit complicated, it took me a while to really understand what happens, but here's a brief explanation:

Y is a namespace generated when YUI is initialised containing the methods from all the loaded modules. Internally, moodle initialises Y and passes it to the module's init function in js_init_call, as the first parameter. To access Y from your init function, you need to do this:

<code javascript>M.my_plugin.init = function(Y) { //Y is now accessible in the scope of init().</code>
However, you probably want access Y in your object's other method's too, so you need to do something like this:

<code javascript>M.my_plugin.init = function(Y) { //Y is now accessible in the scope of init().
this.Y = Y; // this.Y is now accessible from all methods of M.my_plugin
}</code>
For tidiness, I always start any other method using Y with "var Y = this.Y" so I don't have to keep prefixing with this.

You may also find this page useful (or more confusing ) [[Development:How_to_create_a_YUI_3_module]]

== The M.your_plugin thing. What if it isn't a module? What if it's a report somewhere or a local plugin. What's the syntax for this thing? I guess the 'M' is just an arbitrary "thing" ==

First of all, disambiguation of terms:

* A ''YUI Module'' is subset of YUI functionality, contained in it's own namespace, e.g Y.Node
* A ''Moodle Module'', I'm sure you understand.
* A ''Javascript Module'' in this context, is a subset of javascript functionality contained in it's own M. namespace.
Any Moodle plugin can define it's own Javascript Module, whether it's a Moodle Module or a different type of plugin. Usually this will be in the plugin's module.js file, and be called M.plugintype_pluginame (similar to the lang file naming convention), but the object passed as the 4th parameter of $PAGE->requires->js_init_call() allows you to customise this.

A good example of Y's usage that I can point you to is my quickfindlist block.

Take a look at the bottom of get_content() in [https://github.com/marxjohnson/moodle-block_quickfindlist/blob/dev/block_quickfindlist.php block_quickfindlist.php]. This defines $jsmodule (the Javascript module's parameters, including the name, the file it's stored in, and the YUI modules it needs), $jsdata (extra parameters to pass with the init call, in addition to Y), and then passes them, along with the name of the module's init function, to js_init_call(). Note that as it's a block, it uses $this->page in place of $PAGE.

Now look at [https://github.com/marxjohnson/moodle-block_quickfindlist/blob/dev/module.js module.js]. It defines M.block_quickfindlist (which is the module we specified with $jsmodule) and the init() method (which we referenced in js_init_call()). init accepts 6 parameters: Y, and the 5 set in $jsdata. It then stores a copy of Y in M.block_quickfindlist.Y so it can be used in other methods, and uses Y itself to call Y.on(), adding event listeners to the block.
M.block_quickfindlist.search() is defined futher down module.js - it needs acces to Y too, so we create a copy in the method's scope for easy referencing, before using it to make an AJAX request with Y.io(). You can also see use of M.cfg, another Javascript Module, to access the value of wwwroot.

An important thing to note about Y being used all over the place is that as I understand it, Y is only initialised once with all the YUI Modules required by any Javascript Modules on the current page (hence the requirements manager). It's then passed to each module's init function, so they can use it in their own scope.

The actual "core" javascript code to do this would look something like:

<code javascript>
YUI.use('required', 'yui', 'modules', function(Y) {
// YUI.use initialises Y with required modules,
// and passes it to an anonymous function.
// Y is then available to pass to our own init functions
M.block_blockname.init_function(Y);
M.report_reportname.init_function(Y, other, parameters);
});
</code>

== How does Y relate to the yui docs? To step back, how do I work out what methods etc. Y has that I can use? ==

When you request a module for inclusion, it's classes will be attached to the Y namespace. You can see it's classes by going to the YUI documentation for that module, and looking at the API docs. Each module's classes then has a set of properties and methods.

For example the IO module contains the io class. So telling Moodle that your javascript module requires io will give you access to Y.io and all of its methods.
In general, reading the YUI module's documentation and it's examples will give you a good general idea of how to use it's functionality.

It's also worth noting that some modules will create a shortcut method attached directly to Y for convenience. For instance Y.io.io() can also be called using Y.io(), and Y.Node.one() can be called using Y.one().

I'm guessing that some YUI modules are loaded by default ('base' and 'node' probably are), but the requirements manager should make sure that each one's only loaded once. I always define all the YUI Modules my Javascript Module needs, just to make sure.

==See also==

* [http://developer.yahoo.com/yui/3/ YUI documentation]
* [[Javascript FAQ]]

[[Category:Developer]]
[[Category:Javascript]]

Javascript and YUI 3 FAQ

2011-02-09T10:31:47Z

Howardsmiller: /* How do I add an event to make changing a value in a select control submit its parent form? */

{{Moodle 2.0}}A quick primer on the internals of Moodle's javascript, and how to use YUI within it. Based on [http://moodle.org/mod/forum/discuss.php?d=168157 formlibs plus ajax] discussion in the General Developer forum.

== How do I add an event to make changing a value in a select control submit its parent form? ==

When you put the field's name in addElement, it automatically gives it an ID. Say you called it "select1", the id would be "id_select1". There's an exception to this (I can't remember which element it is) in which case you'll need to define an id in the attributes.

You'll then want to get the select and the form using YUI, and attach an event listener:

<code javascript>Y.on('change', submit_form, '#select1');
function submit_form() {
var form = Y.one('#mform1'); // The id for the moodle form is automatically set.
var form.submit();
}</code>

Explanation:
* The first line sets up the event listener. The first parameter says watch for a 'change' of value. The second is the name of the callback function to execute when the change happens. The third is the name of the DOM element that is being watched (in this case the select form element with id='select1'. The second parameter matches the name of the callback function below.
* For a full explanation of event listeners see http://developer.yahoo.com/yui/3/event/

== How do I get that into the page. Is that a 'yui' call or a 'requires_js" call or whatever? ==

The best documentation to read is here: [[Development:JavaScript_guidelines]]

Essentially, you need to define M.your_plugin as an object in a javascript file. You then define the submit_form() function as a method of M.your_plugin, and put the Y.on() call in the init method of the object. You then include the javascript file with $PAGE->requires_js() and call the init method with js_init_call (see docs).

== Also, where does the 'Y' get defined? Is this documented somewhere (I can't find anything)? ==

Y is a bit complicated, it took me a while to really understand what happens, but here's a brief explanation:

Y is a namespace generated when YUI is initialised containing the methods from all the loaded modules. Internally, moodle initialises Y and passes it to the module's init function in js_init_call, as the first parameter. To access Y from your init function, you need to do this:

<code javascript>M.my_plugin.init = function(Y) { //Y is now accessible in the scope of init().</code>
However, you probably want access Y in your object's other method's too, so you need to do something like this:

<code javascript>M.my_plugin.init = function(Y) { //Y is now accessible in the scope of init().
this.Y = Y; // this.Y is now accessible from all methods of M.my_plugin
}</code>
For tidiness, I always start any other method using Y with "var Y = this.Y" so I don't have to keep prefixing with this.

You may also find this page useful (or more confusing ) [[Development:How_to_create_a_YUI_3_module]]

== The M.your_plugin thing. What if it isn't a module? What if it's a report somewhere or a local plugin. What's the syntax for this thing? I guess the 'M' is just an arbitrary "thing" ==

First of all, disambiguation of terms:

* A ''YUI Module'' is subset of YUI functionality, contained in it's own namespace, e.g Y.Node
* A ''Moodle Module'', I'm sure you understand.
* A ''Javascript Module'' in this context, is a subset of javascript functionality contained in it's own M. namespace.
Any Moodle plugin can define it's own Javascript Module, whether it's a Moodle Module or a different type of plugin. Usually this will be in the plugin's module.js file, and be called M.plugintype_pluginame (similar to the lang file naming convention), but the object passed as the 4th parameter of $PAGE->requires->js_init_call() allows you to customise this.

A good example of Y's usage that I can point you to is my quickfindlist block.

Take a look at the bottom of get_content() in [https://github.com/marxjohnson/moodle-block_quickfindlist/blob/dev/block_quickfindlist.php block_quickfindlist.php]. This defines $jsmodule (the Javascript module's parameters, including the name, the file it's stored in, and the YUI modules it needs), $jsdata (extra parameters to pass with the init call, in addition to Y), and then passes them, along with the name of the module's init function, to js_init_call(). Note that as it's a block, it uses $this->page in place of $PAGE.

Now look at [https://github.com/marxjohnson/moodle-block_quickfindlist/blob/dev/module.js module.js]. It defines M.block_quickfindlist (which is the module we specified with $jsmodule) and the init() method (which we referenced in js_init_call()). init accepts 6 parameters: Y, and the 5 set in $jsdata. It then stores a copy of Y in M.block_quickfindlist.Y so it can be used in other methods, and uses Y itself to call Y.on(), adding event listeners to the block.
M.block_quickfindlist.search() is defined futher down module.js - it needs acces to Y too, so we create a copy in the method's scope for easy referencing, before using it to make an AJAX request with Y.io(). You can also see use of M.cfg, another Javascript Module, to access the value of wwwroot.

An important thing to note about Y being used all over the place is that as I understand it, Y is only initialised once with all the YUI Modules required by any Javascript Modules on the current page (hence the requirements manager). It's then passed to each module's init function, so they can use it in their own scope.

The actual "core" javascript code to do this would look something like:

<code javascript>
YUI.use('required', 'yui', 'modules', function(Y) {
// YUI.use initialises Y with required modules,
// and passes it to an anonymous function.
// Y is then available to pass to our own init functions
M.block_blockname.init_function(Y);
M.report_reportname.init_function(Y, other, parameters);
});
</code>

== How does Y relate to the yui docs? To step back, how do I work out what methods etc. Y has that I can use? ==

When you request a module for inclusion, it's classes will be attached to the Y namespace. You can see it's classes by going to the YUI documentation for that module, and looking at the API docs. Each module's classes then has a set of properties and methods.

For example the IO module contains the io class. So telling Moodle that your javascript module requires io will give you access to Y.io and all of its methods.
In general, reading the YUI module's documentation and it's examples will give you a good general idea of how to use it's functionality.

It's also worth noting that some modules will create a shortcut method attached directly to Y for convenience. For instance Y.io.io() can also be called using Y.io(), and Y.Node.one() can be called using Y.one().

I'm guessing that some YUI modules are loaded by default ('base' and 'node' probably are), but the requirements manager should make sure that each one's only loaded once. I always define all the YUI Modules my Javascript Module needs, just to make sure.

==See also==

* [http://developer.yahoo.com/yui/3/ YUI documentation]
* [[Javascript FAQ]]

[[Category:Developer]]
[[Category:Javascript]]

Development:JavaScript guidelines

2011-02-08T13:20:53Z

Howardsmiller: /* Getting Moodle to load your JavaScript files */

{{Moodle 2.0}}

These guidelines can only be applied fully from Moodle 2.0 onwards, because they rely on our new API to facilitate use of JavaScript.

When writing JavaScript for earlier versions of Moodle, please try to follow these guidelines in spirit and use the '''require_js''' function in place of $PAGE->requires->js_module/yui2_lib.

==General principles==

===Moodle should be usable without JavaScript===

Everything in Moodle should work with JavaScript turned off. This is important for accessibility, and in line with the principles of [[Development:Unobtrusive_Javascript|unobtrusive JavaScript]] and [[Development:Progressive_enhancement|progressive enhancement]].

===Minimise inline JavaScript===

Almost all JavaScript code should be in separate .js files. There should be the smallest possible amount of JavaScript inline in the HTML code of pages.

The only <script> tags in the HTML should be
# <script src=... tags to include the necessary .js files.
# Simple function calls to trigger initialisation and pass data from PHP to JavaScript. For example <script type="text/javascript">initialise_my_widget('some', 'data', 123);</script>.

Even these small amounts of JS you should not output directly. They will be generated automatically by calls to the $PAGE->requries->js_init_call() API. See below for details.

You should not use old-fashioned onXXX="event_handler" attributes in the HTML. Use Modern DOM events. The YUI events library makes this easy.

=== JavaScript libraries ===

* The official JavaScript library for Moodle is [[Development:YUI|YUI]]. That may not be your favourite, but it's the one that was chosen after careful research, so live with it.

* Moodle also has its own JavaScript library code, packaged into in various JavaScript modules.

* Moodle uses the '''TinyMCE''' HTML editor.

===When to include the JavaScript===

As per [http://developer.yahoo.com/performance/rules.html Yahoo's best practice guidelines], load and execute the JavaScript as late as possible, ideally the script tags should be the last thing before the </body> close tag. (This is the default behaviour with Moodle's JavaScript handling functions like $PAGE->requries->js_init_call().)

Since everything should work without JavaScript, load and initialising your scripts only after everything else on the page has loaded should not be a problem and will increase the perceived page-load performance for users.

===Minimise the number of .js files===

Try not to use too many different .js files. Each separate file that the browser has to load incurs an overhead.

On the other hand, organise the JavaScript logically to ease maintenance, and don't include large amounts of irrelevant JavaScript code. Code that is loaded but never used is a waste of time.

So, if you are writing a new module that needs its own JavaScript, try starting with a single file mod/mymod/module.js. If you find that you are writing a lot of JavaScript that is only needed when the teacher edits your module, but is not needed by students, then consider splitting that code into a separate file like mod/mymod/edit.js, and only including it where needed.

==How to achive these general principles in Moodle==

The rest of this page explains how you can achieve the above goals.

===Getting Moodle to load your JavaScript files===

Everything required by the current page is tracked by the $PAGE->requires object, which is an instance of the [http://phpdocs.moodle.org/HEAD/moodlecore/page_requirements_manager.html page_requirements_manager] class defined in lib/outputrequirementslib.php.

The most important method in this class is the ->js_init_call(...) method. You use it like this:

<code php>
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'));
</code>

Note that this will implicitly load the JavaScript code in mod/mymod/module.js, and then call the M.mod_mymod.init_something function passing four string arguments 'some', 'data', 'from', 'PHP'. You can pass any PHP type as an argument. The PHP values are encoded with json_encode before being passed to JavaScript, so numbers, strings, arrays and objects all work.

Sometimes, the code in the JavaScript module mod/mymod/module.js may require some other JavaScript libraries to be loaded, or it may require some language strings. In that case you need to use the full form of js_init_call:

<code php>
$jsmodule = array(
'name' => 'mod_mymod',
'fullpath' => '/mod/mymod/module.js',
'requires' => array('base', 'io', 'node', 'json'),
'strings' => array(
array('something', 'mymod'),
array('confirmdelete', 'mymod'),
array('yes', 'moodle'),
array('no', 'moodle')
)
);
$PAGE->requires->js_init_call('M.mod_mymod.init_something', array('some', 'data', 'from', 'PHP'), false, $jsmodule);
</code>
(Naturally, it would be a good idea to put the definition of the $jsmodule array somewhere central like in the locallib.php file.)

The third (boolean) parameter is defined as "Wait for DOM Ready".

The libraries in the 'requires' sub-array are YUI3 (or YUI2) libraries.

The strings are Moodle language strings. In order for Moodle to have correctly determined the user's language, you should only call js_init_call after the call to require_login, which sets the current course, and ensures the user is logged in.

$PAGE->requires keeps track of which files have been included. For example if two other modules both require the YUI base module, then it is only included once.

===JavaScript coding style===

Moodle JavaScript code should should follow the same [[Development:Coding_style|coding style as Moodle PHP code]], allowing for the differences between PHP and JavaScript.

For example, all the rules on ''function_names'', ''class_names'' and ''variablenames'' apply. You should document your code with [http://jsdoc.sourceforge.net/ JSDoc] comments. Layout your JavaScript expressions and statements like the equivalent PHP ones.

Normally, your .js files should simply define things like functions, classes and variables. When the file is loaded, no JavaScript code should actually be executed that has any effect unless it is the sort of code that can safely be executed once per HTML page. This is so that it plays nicely with the require_once-like behaviour of $PAGE->requires->js.

Do not pollute the global JavaScript name-space. Try to package your JavaScript into objects, and put all objects inside the global M object, like the M.mod_mymod example above.

===Different content when JavaScript is on or off===

Remember the overriding principals that everything should work with JavaScript off, and we should adopt a [[Progressive enhancement]] approach. However, there are valid reasons why sometimes you need different content with JavaScript is on or off. We can break it down into three cases:

====Content that should only be visible with JavaScript off====

An example of this is the automatic search when you are looking for a user to assign a role to. With JavaScript on, the search automatically starts after a delay. With JavaScript off, we want an explicit Search button visible.

To handle this case, Moodle automatically add a class 'jsenabled' to the body tag using JavaScript. So you just need to add a rule like
<code css>
body.jsenebled .mywidget .submitbutton {
display: none;
}
</code>
to the stylesheet, and the button will be invisible if JavaScript is enabled.

An alternative strategy is to remove the particular bits of HTML from the page using DOM methods. However, if your JavaScript is only loaded at the end of the page, it may take some time for the extra content to disappear, which leads to a disconcerting flicker in the page.

Yet another approach is the old-fashioned <noscript> tag.

====Content that needs to be visible right away when JavaScript is on====

An example is the <nowiki>[+] or [-]</nowiki> icon that can be used to expand/collapse each block if JavaScript is on.

We can divide this into two subcases:

=====Content generated by PHP code=====

Where the HTML for the JavaScript only widget is generated by PHP, we can make it invisible when JavaScript is off using just CSS:
<code css>
.mywidget {
display: none;
}
body.jsenabled .mywidget {
display: block;
}
</code>
However, it could be argued that this approach is not really progressive enhancement.

=====Content generated by JavaScript code=====

This is more in keeping with progressive enhancement, and this is the way that the expand/collapse block icon is handled.

We build the icon using DOM methods. The only problem is that as the JavaScript is loaded in the footer, there is a small delay before the icons appear. Since when the icons appear, they do not cause other content on the page to move around, that is OK. Also, this delayed appearance is becoming more common on the web. For example, on http://twitter.com/, some things only appear a moment after the main part of the page has finished loading.

However, it the delayed appearance is really a problem, then the only solution is to embed the JavaScript that generates the extra content in the middle of the HTML, using the js_writer class.

====Content that only appears when the user does something, when JavaScript is on====

An example of this is something like file picker dialog that appears when you add an image to some content in the HTML editor, or the one that pops up when you click 'Add new question' in the quiz editing interface.

We have the same two sub-cases:

=====Content generated by PHP code=====

In this case, you need to make sure the content is always covered by a ''display: none;'' rule in the CSS, but then when the user takes an action like clicking a button to reveal the extra content, you need to override that class name some how, perhaps by adding or removing a className using JavaScript.

=====Content generated by JavaScript code=====

In this case, there is no problem. When the use triggers the extra content to appear, it is constructed using DOM methods. There may be a tiny delay, but the chances are that it will hardly be noticeable to the human eye.

If the content generation may be slow (perhaps because it is waiting for an Ajax request) then you should display a progress icon. See, for example, the loading of the tooltip for help icons.

===Don't break XHTML strict!===

Remember that all Moodle output must be [[Development:XHTML|XHTML strict]], and that means that the HTML output must be well-formed XML. Inline JavaScript is a great way to break that. (JavaScript uses the < and & symbols that must be escaped in XML.) Therefore any JavaScript inline in the HTML should be escaped in a CDATA section:

<code xml>
<script type="text/javascript">
//<![CDATA[

// Your JavaScript code goes here.

//]]>
</script>
</code>

Of course, if you are following the above guidelines and putting most of your JavaScript in separate .js files, and using $PAGE->requires->js_init_call, then this is taken care of for you automatically.

==Testing==

JavaScript support varies a lot between browsers. JavaScript needs to be tested in IE, Firefox and Safari. Ideally, Moodle will support [http://developer.yahoo.com/yui/articles/gbs/ all the browsers that YUI does].

==See also==

* [[Development:Coding|The rest of Moodle coding guidelines]]
* [http://developer.yahoo.com/yui/ YUI documentation]
* [[Javascript FAQ]]
* [[Development:Unobtrusive Javascript]]
* [[Development:JavaScript functions]]
* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]

[[Category:Coding guidelines|JavaScript guidelines]]
[[Category:Javascript|JavaScript guidelines]]
[[Category:AJAX|JavaScript guidelines]]

[[ja:開発:Javaスクリプトガイドライン]]

Development talk:JavaScript guidelines

2011-02-08T11:20:16Z

Howardsmiller: /* Some information on using YUI calls? */

== event handlers ==
Should there be a recommendation to use YUI event handlers instead of JavaScript's inline event handlers? This might be better for cross-browser compatibility. --[[User:Frank Ralf|Frank Ralf]] 09:24, 15 June 2009 (UTC)

:Good idea--[[User:Tim Hunt|Tim Hunt]] 03:16, 16 June 2009 (UTC)

== Getting Moodle to load your JavaScript files ==
are in_head and asap now obsolete?
It seems in_head is replaced by the second parameter to the js class constructor, is there an alternative for asap? --[[User:Alastair Hole|Alastair Hole]] 17:46, 13 June 2010 (UTC)

: Yes. They are obsolete. If you want to output JS in the middle of the page, you should not just do that using the js_writer class. However, the only javascript like that should be simple function calls to initialise things. It is much better to have your javascript in the footer, and if you plan for that in advance, it is normally easy to do. (I will now update this page, to remove mention of obsolete stuff.)--[[User:Tim Hunt|Tim Hunt]] 19:27, 13 June 2010 (UTC)

== Some information on using YUI calls? ==
Unless I've missed something, I can't see any information on how to use the YUI library in Moodle 2. It's not intuitively obvious either. --[[User:Howard Miller|Howard Miller]] 10:44, 8 February 2011 (UTC)

== What does M.mod_mymod.init_something in general ==
What if my 'module' is a block or a report or some-such? What is the general syntax of this string? --[[User:Howard Miller|Howard Miller]] 11:20, 8 February 2011 (UTC)

Development talk:JavaScript guidelines

2011-02-08T10:44:14Z

Howardsmiller: /* Getting Moodle to load your JavaScript files */

Development:YUI

2011-02-08T10:36:29Z

Howardsmiller: Wrong url

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].

==Note==

Some of the following information will be out of date when Moodle 2.0 is released. Please see [[Development:JavaScript guidelines]] for the latest information.

==Getting started==

One approach is to find an example that is close to what you want, either in the Moodle code, or on the [http://developer.yahoo.com/yui/ Yahoo Developer Website]. Then adapt it to your needs.

The entire YUI libraries are all part of a single YAHOO object, so they will not clash with other code. You then use them like this:
<code javascript>
YAHOO.util.Event.onDOMReady(...);
</code>

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

<code php>
require_js(array('yui_yahoo', 'yui_event'));
</code>

As you can see, you need only refer to the libraries by name. You don't need to know the full path. The [http://xref.moodle.org/lib/ajax/ajaxlib.php.source.html#l6 ajax_get_lib()] function in ''/lib/ajax/ajaxlib.php'' has the complete list of libraries.

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.

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

<code php>
document.body.className += ' yui-skin-sam';
</code>

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

<code php>
background: url(../../whatever.png);
</code>

and paste them into your styles.php below the css include you've added, but looking like this:

<code php>
background: url(<?php echo $CFG->wwwroot ?>/lib/yui/whatever.png);
</code>

== 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 Web Developer Toolbar], [https://addons.mozilla.org/en-US/firefox/addon/1843 Firebug] and [https://addons.mozilla.org/en-US/firefox/addon/5369 YSlow] extensions loaded (see also [[Development:Firebug]] and [[Web developer extension]]).

* 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.

== See also ==

* [http://developer.yahoo.com/yui/ The official YUI documentation]
* [[JavaScript FAQ]]

[[Category:Javascript|YUI]]
[[Category:AJAX|YUI]]
{{CategoryDeveloper}}

Development:lib/formslib.php Usage

2011-02-06T20:49:01Z

Howardsmiller: /* Basic Usage in A Normal Page */

{{Formslib}}
==Usage of Formslib==

There are many phpdoc style comments in lib/formslib.php

course/edit.php and the included course/edit_form.php provide a good example of usage of this library.

Also see the PEAR docs for [http://pear.php.net/package/HTML_QuickForm/ HTML_QuickForm docs] I found this [http://pear.php.net/manual/en/package.html.html-quickform.tutorial.php quick tutorial] and this [http://www.midnighthax.com/quickform.php slightly longer one] particularly useful.

We created some special wrapper functions for moodle. Function $mform->get_data() returns an object with the contents of the submitted data or returns null if no data has been submitted or validation fails.

===Basic Usage in A Normal Page===

Generally the structure of a page with a form on it looks like this :

<code php>
require_once('pathtoformdescription');
//you'll process some page parameters at the top here and get the info about
//what instance of your module and what course you're in etc. Make sure you
//include hidden variable in your forms which have their defaults set in set_data
//which pass these variables from page to page

$mform = new yourmod_formfunction_form();//name of the form you defined in file above.
//default 'action' for form is strip_querystring(qualified_me())
if ($mform->is_cancelled()){
//you need this section if you have a cancel button on your form
//here you tell php what to do if your user presses cancel
//probably a redirect is called for!
} else if ($fromform=$mform->get_data()){
//this branch is where you process validated data.

} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.
//setup strings for heading
print_header_simple($streditinga, '',
"<a href=\"$CFG->wwwroot/mod/$module->name/index.php?id=$course->id\">$strmodulenameplural</a> ->
$strnav $streditinga", $mform->focus(), "", false);
//notice use of $mform->focus() above which puts the cursor
//in the first form field or the first field with an error.

//call to print_heading_with_help or print_heading? then :

//put data you want to fill out in the form into array $toform here then :

$mform->set_data($toform);
$mform->display();
print_footer($course);

}
</code>

You are encouraged to look at '''lib/formslib.php''' to see what additional functions and parameters are available. Available functions are well commented.

===Defining Your Form Class===

The form class tells us about the structure of the form. You are encouraged to put this in a file called {function}_form.php probably in the same folder in which the page that uses it is located. The name of your class should be {modname}_{function}_form eg. forum_post_form or course_edit_form. These classes will extend class moodleform.

Note the name you give the class is used as the id attribute of your form in html (any trailing '_form' is chopped off'). Your form class name should be unique in order for it to be selectable in CSS by theme designers who may want to tweak the css just for that form.

====definition()====

[[Development:lib/formslib.php_Form_Definition|Help is here for defining your form]] by defining a function definition() in your form class that sets up your form structure.

===Use in Activity Modules Add / Update Forms===

Syntax is the same in activity modules to create your update / add page. We are still supporting mod.html but if you want to use the new formslib then you can in Moodle 1.8 just include in your module directory the file mod_form.php instead of mod.html and it will be automatically detected. Inside this file you define a class with class name '{modname}__mod_form' which extends the class 'moodleform_mod'. See many examples of the core modules which have been converted to use formslib already.

====defaults_preprocessing====

For activity modules you use the same syntax to define your form. You may also want to override method defaults_preprocessing this can be used to take the data from the data base and tell the form how to fill out defaults in the form with this data. For example in the forum module in forum/mod_form.php we needed to tick an enable check box if a date had been selected in the date select. Normally data is loaded from the database and directly loaded into form fields with the same name as the database record you only need to use defaults_preprocessing if there isn't this one to one relationship. Another example is the lesson/mod_form.php which takes the data from the database and unserializes it. choice/mod_form.php shows an exampe of loading data from another db table referred to by a foreign key, to include in the form.

====Post Processing Still Done in lib.php Functions====

Post processing of data is done in lib.php functions modname_add_instance and modname_update_instance after the data has been validated. When migrating a form often little changes need to be made in the post processing. An exception is that date and date_time_selector fields automatically have their submitted data turned into timestamps so you don't need to do this in your add and update functions anymore.

====Automatically Including Standard Activity Module Form Elements====

Standard activity module form elements are automatically included using the moodleform_mod method standard_coursemodule_elements(). The default is to include a visibility and groupsmode select box and to include all necessary hidden fields. You can pass a parameter false to tell the method that your module doesn't support groups and so you don't want the groupsmode select button.

[[Category:Formslib]]

Development:lib/formslib.php Form Definition

2011-02-06T20:41:32Z

Howardsmiller: /* definition() */

{{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>

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

==== 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 a couple of important improvements:

# The 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 [[Development:lib/formslib.php_add_checkbox_controller|checkbox controller]]
#The 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.

=== choosecoursefile ===
<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.

<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,
'applydst' => true,
'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,
'applydst' => true,
'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.

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

<code php>
$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));
$mform->setType('text', PARAM_RAW);
$mform->addRule('text', null, 'required', null, 'client');

$mform->addElement('format', 'format', get_string('format'));
</code>

You can supply a fourth param to htmleditor of an array of options :

<code php>

array(
'canUseHtmlEditor'=>'detect',
'rows' => 10,
'cols' => 65,
'width' => 0,
'height'=> 0,
'course'=> 0,
);
//options same as print_textarea params
//use rows and cols options to control htmleditor size.
</code>

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

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

<code php>
$radioarray=array();
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = &MoodleQuickForm::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.

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

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

===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 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').

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

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

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

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

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:

* @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

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:

1. get_string($identifier, $component): The title of the help page
2. 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.

==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=null)

* 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 unless a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);

The possible choices here are in the function lockoptionsall in lib/javascript-static.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]]

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

Development talk:lib/formslib.php Form Definition

2011-02-06T13:06:47Z

Howardsmiller:

There's items on here (e.g. 'duration') that are 2.0 only. Please can people adding them mark them as such to avoid confusion. Ta --[[User:Howard Miller|Howard Miller]] 11:42, 23 July 2009 (UTC)

: Hi Howard, You can just add <nowiki>{{Moodle 2.0}}</nowiki> to those items. I did that for 'duration'. --[[User:Frank Ralf|Frank Ralf]] 11:54, 23 July 2009 (UTC)

== Use Static elements with care? ==

Why are static elements listed as being used with care?

== ''Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.'' ==

I'm really not sure what this means. Does it actually mean "do not create elements that are conditional upon the values of other submitted elements" as opposed to not creating conditional elements at all? Lots of forms have conditional elements --[[User:Howard Miller|Howard Miller]] 13:06, 6 February 2011 (UTC)

Development:Development hints and tips

2011-02-04T10:36:20Z

Howardsmiller: /* Use a Version Control system */

{{Work in progress}}

There is a great deal of development experience amongst the Moodle developers. This page is some general hints and tips that may help people starting out in PHP and Moodle development. These apply as much to people writing their own plugins as core developers.

== Avoid writing code in the first place ==

Always take the trouble to find if there is another (existing) way to do what you need. Failing that, does a plugin or option already exist. Failing that, does something exist that you can modify. Failing that, is there a library (or libraries) that exist to reduce your effort. Lastly write the code yourself. Existing, tested code is always to be preferred - more so if it has an extensive user base.

== Follow the Coding Guidelines ==

Moodle has a well developed set of [[Development:Coding|Coding Guidelines]]. Read them and follow them. It's surprising how many custom plugins for Moodle do not. It instantly prevents your code from being incorporated in core Moodle.

Pay particular attention to the security information. A basic understanding of security in a web development environment is no longer optional. If you don't know what an XSS attack or an SQL injection are then you need to find out.

== When in Rome, do like the Romans ==

The Coding Guidelines do not describe every possible situation. When you find yourself in that situation, try to follow the example of how things are done in other parts of Moodle. Just because Moodle is not written the way you would do it if you were starting from scratch does not matter. In a large project like Moodle, it is more important to keep the code consistent than it is to satisfy your personal prejudices about how code should be. That makes it easier to maintain the code, and if you start writing Moodle-style code, you will find it easier to understand the other bits of Moodle code you look at.

Of course, some parts of Moodle are just badly written. You should not copy what is done in those places. ;-) When looking for examples to follow, try to find code that has been written recently by one of the reliable core developers.

Getting involved in a large Open Source project can be a bit of a culture shock if you are not used to it. Lots of advice (and, sometimes, constructive criticism) is readily available. Don't be afraid to ask - that's what the General Developer Forum is for.

== Use a Version Control system ==

If you are developing without a version control system then you are doing it wrong. The benefits run well beyond just being able to keep past versions of your code. Moodle uses [[Development:Git tips|Git]] for developing so it makes sense to learn it. This is a powerful distributed system and does take a bit of getting your head around but the effort is worth it.

== Find an editor or IDE that works for you and learn it properly ==

There are many different development platforms from complex Integrated Development Environments (IDEs) to simple editors and command line tools. Choose something that works for you and then take the trouble to learn how to use it properly.

Find the editor's customisation options and make it fit in with Moodle's coding guidelines - example, most editors can be persuaded to use the correct number of spaces (4 in Moodle's case) rather than the tab character.

== Comment effectively ==

Don't be shy about putting comments in code. If the code deserves a blank line it probably deserves a comment. It's obvious what the code does now but it won't be in six months.

== KISS (Keep It Simple Stupid) ==

Albert Einstein didn't ''actually'' say "Everything should be made as simple as possible, but no simpler" but it would still have been good advice if he had. Take the trouble to come up with the simplest solution to the problem at hand. Resist the temptation to add code for things that you ''might'' need in the future or ''might'' be required one day. They usually never happen and you can always change the code later if requirements change. For example, don't use some insanely complex object factory when old-fashioned procedural programming will do. Don't use old-fashioned procedural programming when a class-hierarchy models the real-world problem more intuitively. Avoid complex abstractions where they are not actually needed to get the job done. Any additional code increases the risk of bugs, security problems and maintenance issues in the future.

== Use good variable and function names ==

It should be easy and obvious to pick a name for a variable or a function. If it isn't you are either trying to make that function too complicated (simplify and break it up) or you haven't fully understood what you are trying to do (another cup of coffee?). Names should always say what they are for or what they do - plainly.

== Pretty code is good code ==

Seriously! Code that is well laid out and easy to read is easy to debug and to modify. Make the effort to lay out code so it looks good and is easy to read through. Don't be afraid to break something nasty into several lines so that it reads well. It's tempting to make one line of code do something incredibly complex but you won't feel so clever when you can't remember how it works.

== Write Plugins. Use APIs ==

Always, when developing custom features, write a standard plugin in preference to modifying core code. Even if you have to compromise the functionality a bit. Most Moodle plugin structures are able to easily create database structures, handle role capabilities, define language files and ease future updates. Furthermore, the end result can all be delivered in one simple zip file. It doesn't rely on one particular build of Moodle either. These are real and big advantages. A core code patch is only guaranteed to work with the exact build it was written with, it probably won't survive upgrades and patches are notoriously difficult to apply properly - even for experienced developers. If in doubt look at blocks - you can do an awful lot with a block (even if it's never actually added as a visible block). Blocks are reasonably easy to understand and to develop, too.

Similarly, take the trouble to investigate existing Moodle APIs and library calls. Your code will last longer and be more reliable.

== Separate out functionality ==

Or... don't muddle up the user interface with the database access and other logic. For example, alarm bells should ring if you are writing functions like '''get_data_and_display()'''. It is a much better idea to write '''get_data()''' and then '''display_data()'''. The effort is little or no different, however, the end result is often easier to follow and (say) if someone asks you to dump the data to Excel rather than display it the latter method saves you a costly refactor. Even if you are not writing functions and your logic is all on one page try to split things into logical blocks - read the input, THEN do the calculations and database access, THEN display the output. It will be easier to refactor or to modify.

== Don't Make Me Think ==

It's actually a title of a book by Steve Krug (and it should be obligatory reading for all web designers), however, the point is really about Usability. Usability is hard but you still have to try. Don't make your users have to think. Good documentation is important but it's hard to keep it up to date and it's a partial failure if someone has to resort to reading it. In particular, be quite clear that ordinary Moodle users don't care about clever implementation or super flexibility. Anything that complicates the job of getting effective learning materials to students is "a bad thing". Anything that in the name of adding flexibility or functionality makes an ordinary user's job more complex is a regression. If something must be done then the code must do it - do not burden the user.

Force yourself to think like a user and not a programmer. A clever, elegant solution to a programming problem is not guaranteed to result in a feature that is simple and intuitive to use. Look at the forums. If lots of people are having trouble using a feature then you need to consider if the feature is doing the job well enough.

It should be hard (or even better impossible) for users to break things. The greatest invention ever was the undo button - it doesn't only protect the user against mistakes it allows them to safely experiment. Users don't learn to use software by reading the manual - they experiment and guess. Make it easy for them.

There's some guidelines (currently under development) in [[Development:Moodle User Interface Guidelines|User Interface Guidelines]]

== Let the database do the grunt work ==

If there's a choice let the database do the work of searches. Especially if multiple tables are involved. It's what it was designed to do. It can be tempting, especially if your SQL knowledge isn't too good, to tie together multiple database queries with PHP loops and the like. Always consider using a single database call instead. Always try to use the basic Moodle database API functions before writing custom SQL (portability!).

Having said all that, optimising databases (especially when datasets get large) is a subject in itself. Nearly all web development involves database interactions so even basic db admin skills are very valuable and worthwhile acquiring.

== Generate helpful error messages ==

If you generate an error message, consider if it 'really' helps the user fix the problem. Be as specific as possible. If you can give information that will help resolve the problem rather than just say it happened then do so. BUT... you also have to consider security. Don't give away information that might help a hacker. You might want to consider debugging level (is it on?) and/or who the user is (you might give an administrator more information).

You should also try to trap as many possible errors as possible. If a function returns a fail condition then you would need to have a very good reason not to check it. This helps avoid the highly unpopular "white screen of death".

Add extra debugging code (call ''debugging()'' )if you think it might help. This is especially true for functions that have complex configuration or external dependencies (i.e. lots that can go wrong).

Never write an error message that looks something like "An unknown error occurred". You might as well not bother as this doesn't help anybody fix the problem.

== Don't make empty pages and blocks ==

If you write code that returns (typically) a block (but you can do it lots of places) think very carefully before returning nothing. An empty return for a block causes the block not to be displayed at all. Unless you have a very compelling reason to do this avoid it. It will confuse the user - they add a block and then nothing happens. If some capability or configuration is required consider displaying a message to help them. In a report or other pages that return variable data, be careful how you deal with empty data sets. Always display something like "no data found" rather than a blank page. Blank pages make users think something is broken.

== Turn on Debugging and fix those notices and warnings ==

If you get PHP warnings or notices when [[Debugging]] is switched on the problem is '''not''' that debugging has been left on, the problem is that there are bugs in your code. There is no excuse for not checking for and then fixing notices and warnings. To not do so is shoddy at best.

== Expand Moodle Docs ==

If something you want to do isn't documented (or isn't documented well or fully) and you figure it out - document it. Don't write it in your notebook or your company's closed Wiki, put it in the docs here. It's there for you next time and for everyone else as well.

== More tips please ==
(add your own!)

[[Category:Developer]]

Talk:Grade import

2011-02-03T10:41:55Z

Howardsmiller:

The instructions on this page are very unclear. They vaguely instruct you to just "export some grades using the corresponding export format", "edit the export file as appropriate and save it" and then "upload your previously saved file".
It doesn't have any details. For instance, what fields CAN you include in the export file (what fields are optional), what fields MUST you include (are compulsory) and what fields CAN'T you include (e.g. course totals)?

In http://moodle.org/mod/forum/discuss.php?d=85944#p381209 Tim Hunt says: "... please be aware that you cannot import the course total. The gradebook handles the aggregation of grades, and you can edit this aggregation, or even override the course total manually, but you cannot import it using a CSV file." This is valuable information but it seems to have been completely omitted from the import/export documentation.

What makes it more confusing is that the https://docs.moodle.org/en/Grade_export documentation (which is also very vague)
says that you can include the Course Total in the export file but the implications thereof aren't explained. If users are exporting data just for the purpose of getting the format of the IMPORT file (as the instructions on the https://docs.moodle.org/en/Grade_import page tell you to do) they should NOT select the Course Total in the export. This should be clarified in the documentation.

Also, the instructions for importing grades are quite vague, e.g.:

Point 2 says: "Edit the export file as appropriate and save it." What is "appropriate" and when is it appropriate?

Point 5 says: "Set options as required." What options are these?

And the Grade_import page also says: "You need two permissions to import grades: (1) general permission to import grades and (2) permission to import grades in a particular format. For example, to import CSV grades you need:

moodle/grade:import ("Import grades") = Allow
gradeimport/csv:view ("Import grades from CSV") = Allow"

How and where do you set these permissions? Are they code changes that you have to make?

Finally, no mention is made of what format the grades must be in when you import them into Moodle. Can you import grades as percentages, or MUST they be the actual numerical values? Do users have the option of importing grades as percentages or is it assumed that grades will always be in their numerical form?

I don't know the answers so I can't update the documentation...

[[User:Luis de Vasconcelos|Luis de Vasconcelos]] 02:13, 27 October 2008 (CDT)

I'll be a little more forthright than the above. Without an explanation of the file format this is all a bit useless. --[[User:Howard Miller|Howard Miller]] 10:41, 3 February 2011 (UTC)

Development:Development hints and tips

2011-01-30T20:51:50Z

Howardsmiller: /* Generate helpful error messages */

{{Work in progress}}

There is a great deal of development experience amongst the Moodle developers. This page is some general hints and tips that may help people starting out in PHP and Moodle development. These apply as much to people writing their own plugins as core developers.

== Avoid writing code in the first place ==

Always take the trouble to find if there is another (existing) way to do what you need. Failing that, does a plugin or option already exist. Failing that, does something exist that you can modify. Failing that, is there a library (or libraries) that exist to reduce your effort. Lastly write the code yourself. Existing, tested code is always to be preferred - more so if it has an extensive user base.

== Follow the Coding Guidelines ==

Moodle has a well developed set of [[Development:Coding|Coding Guidelines]]. Read them and follow them. It's surprising how many custom plugins for Moodle do not. It instantly prevents your code from being incorporated in core Moodle.

Pay particular attention to the security information. A basic understanding of security in a web development environment is no longer optional. If you don't know what an XSS attack or an SQL injection are then you need to find out.

== When in Rome, do like the Romans ==

The Coding Guidelines do not describe every possible situation. When you find yourself in that situation, try to follow the example of how things are done in other parts of Moodle. Just because Moodle is not written the way you would do it if you were starting from scratch does not matter. In a large project like Moodle, it is more important to keep the code consistent than it is to satisfy your personal prejudices about how code should be. That makes it easier to maintain the code, and if you start writing Moodle-style code, you will find it easier to understand the other bits of Moodle code you look at.

Of course, some parts of Moodle are just badly written. You should not copy what is done in those places. ;-) When looking for examples to follow, try to find code that has been written recently by one of the reliable core developers.

Getting involved in a large Open Source project can be a bit of a culture shock if you are not used to it. Lots of advice (and, sometimes, constructive criticism) is readily available. Don't be afraid to ask - that's what the General Developer Forum is for.

== Use a Version Control system ==

If you are developing without a version control system then you are doing it wrong. The benefits run well beyond just being able to keep past versions of your code. Moodle currently uses CVS for core development but this is probably a poor (out of date) choice for a new project. Moodle uses [[Development:Git tips|Git]] for developing so it makes sense to learn it. This is a powerful distributed system and does take a bit of getting your head around but the effort is worth it.

== Find an editor or IDE that works for you and learn it properly ==

There are many different development platforms from complex Integrated Development Environments (IDEs) to simple editors and command line tools. Choose something that works for you and then take the trouble to learn how to use it properly.

Find the editor's customisation options and make it fit in with Moodle's coding guidelines - example, most editors can be persuaded to use the correct number of spaces (4 in Moodle's case) rather than the tab character.

== Comment effectively ==

Don't be shy about putting comments in code. If the code deserves a blank line it probably deserves a comment. It's obvious what the code does now but it won't be in six months.

== KISS (Keep It Simple Stupid) ==

Albert Einstein didn't ''actually'' say "Everything should be made as simple as possible, but no simpler" but it would still have been good advice if he had. Take the trouble to come up with the simplest solution to the problem at hand. Resist the temptation to add code for things that you ''might'' need in the future or ''might'' be required one day. They usually never happen and you can always change the code later if requirements change. For example, don't use some insanely complex object factory when old-fashioned procedural programming will do. Don't use old-fashioned procedural programming when a class-hierarchy models the real-world problem more intuitively. Avoid complex abstractions where they are not actually needed to get the job done. Any additional code increases the risk of bugs, security problems and maintenance issues in the future.

== Use good variable and function names ==

It should be easy and obvious to pick a name for a variable or a function. If it isn't you are either trying to make that function too complicated (simplify and break it up) or you haven't fully understood what you are trying to do (another cup of coffee?). Names should always say what they are for or what they do - plainly.

== Pretty code is good code ==

Seriously! Code that is well laid out and easy to read is easy to debug and to modify. Make the effort to lay out code so it looks good and is easy to read through. Don't be afraid to break something nasty into several lines so that it reads well. It's tempting to make one line of code do something incredibly complex but you won't feel so clever when you can't remember how it works.

== Write Plugins. Use APIs ==

Always, when developing custom features, write a standard plugin in preference to modifying core code. Even if you have to compromise the functionality a bit. Most Moodle plugin structures are able to easily create database structures, handle role capabilities, define language files and ease future updates. Furthermore, the end result can all be delivered in one simple zip file. It doesn't rely on one particular build of Moodle either. These are real and big advantages. A core code patch is only guaranteed to work with the exact build it was written with, it probably won't survive upgrades and patches are notoriously difficult to apply properly - even for experienced developers. If in doubt look at blocks - you can do an awful lot with a block (even if it's never actually added as a visible block). Blocks are reasonably easy to understand and to develop, too.

Similarly, take the trouble to investigate existing Moodle APIs and library calls. Your code will last longer and be more reliable.

== Separate out functionality ==

Or... don't muddle up the user interface with the database access and other logic. For example, alarm bells should ring if you are writing functions like '''get_data_and_display()'''. It is a much better idea to write '''get_data()''' and then '''display_data()'''. The effort is little or no different, however, the end result is often easier to follow and (say) if someone asks you to dump the data to Excel rather than display it the latter method saves you a costly refactor. Even if you are not writing functions and your logic is all on one page try to split things into logical blocks - read the input, THEN do the calculations and database access, THEN display the output. It will be easier to refactor or to modify.

== Don't Make Me Think ==

It's actually a title of a book by Steve Krug (and it should be obligatory reading for all web designers), however, the point is really about Usability. Usability is hard but you still have to try. Don't make your users have to think. Good documentation is important but it's hard to keep it up to date and it's a partial failure if someone has to resort to reading it. In particular, be quite clear that ordinary Moodle users don't care about clever implementation or super flexibility. Anything that complicates the job of getting effective learning materials to students is "a bad thing". Anything that in the name of adding flexibility or functionality makes an ordinary user's job more complex is a regression. If something must be done then the code must do it - do not burden the user.

Force yourself to think like a user and not a programmer. A clever, elegant solution to a programming problem is not guaranteed to result in a feature that is simple and intuitive to use. Look at the forums. If lots of people are having trouble using a feature then you need to consider if the feature is doing the job well enough.

It should be hard (or even better impossible) for users to break things. The greatest invention ever was the undo button - it doesn't only protect the user against mistakes it allows them to safely experiment. Users don't learn to use software by reading the manual - they experiment and guess. Make it easy for them.

There's some guidelines (currently under development) in [[Development:Moodle User Interface Guidelines|User Interface Guidelines]]

== Let the database do the grunt work ==

If there's a choice let the database do the work of searches. Especially if multiple tables are involved. It's what it was designed to do. It can be tempting, especially if your SQL knowledge isn't too good, to tie together multiple database queries with PHP loops and the like. Always consider using a single database call instead. Always try to use the basic Moodle database API functions before writing custom SQL (portability!).

Having said all that, optimising databases (especially when datasets get large) is a subject in itself. Nearly all web development involves database interactions so even basic db admin skills are very valuable and worthwhile acquiring.

== Generate helpful error messages ==

If you generate an error message, consider if it 'really' helps the user fix the problem. Be as specific as possible. If you can give information that will help resolve the problem rather than just say it happened then do so. BUT... you also have to consider security. Don't give away information that might help a hacker. You might want to consider debugging level (is it on?) and/or who the user is (you might give an administrator more information).

You should also try to trap as many possible errors as possible. If a function returns a fail condition then you would need to have a very good reason not to check it. This helps avoid the highly unpopular "white screen of death".

Add extra debugging code (call ''debugging()'' )if you think it might help. This is especially true for functions that have complex configuration or external dependencies (i.e. lots that can go wrong).

Never write an error message that looks something like "An unknown error occurred". You might as well not bother as this doesn't help anybody fix the problem.

== Don't make empty pages and blocks ==

If you write code that returns (typically) a block (but you can do it lots of places) think very carefully before returning nothing. An empty return for a block causes the block not to be displayed at all. Unless you have a very compelling reason to do this avoid it. It will confuse the user - they add a block and then nothing happens. If some capability or configuration is required consider displaying a message to help them. In a report or other pages that return variable data, be careful how you deal with empty data sets. Always display something like "no data found" rather than a blank page. Blank pages make users think something is broken.

== Turn on Debugging and fix those notices and warnings ==

If you get PHP warnings or notices when [[Debugging]] is switched on the problem is '''not''' that debugging has been left on, the problem is that there are bugs in your code. There is no excuse for not checking for and then fixing notices and warnings. To not do so is shoddy at best.

== Expand Moodle Docs ==

If something you want to do isn't documented (or isn't documented well or fully) and you figure it out - document it. Don't write it in your notebook or your company's closed Wiki, put it in the docs here. It's there for you next time and for everyone else as well.

== More tips please ==
(add your own!)

[[Category:Developer]]

Development:Places to search for lang strings

2011-01-25T13:51:35Z

Howardsmiller: /* Defining the search path(s) */

Moodle has a mechanism that allows a number of places to be searched (in order) to find language strings or help files. This enables language strings and help to be packaged with optional plugins and avoids the step of having to copy the language files over to the language directory when a plugin is installed. This page provides some information about this mechanism which might be useful to plugin developers or those wishing to add a completely new pluggable feature to moodle.

This page covers both how to set up (core) Moodle to support a new plugabble resource and how to incorporate language elements in a plugin. Plugin writers really only need to read the last bit.

== Basic concepts ==

When it is required to lookup a string or point to a help file, two basic items of information are required. The first is the name of the string (or the help filename) and the name of the module in which it can be found. For example, '''get_string('editingquiz','quiz')''' returns "Editing Quiz" in the current language; a call to '''help.php?module=label&file=mods.html''' displays the help for a label, again in the current language.

Plugin support extends this by defining a new format for the module name so that certain resources can both exist in core, the core distribution (and language packs) and be installed as options. The module name becomes ''type''_''plugin'', where ''type'' is a generic name common to the plugin type and ''plugin'' is the name of the individual item. To illustrate this, here is an example. Blocks are a pluggable resource - the ''type'' name is '''block_''' and the ''plugin'' name is the name of the individual block. Some examples of block module names are '''block_search''' (''type'' is '''block_''' and ''plugin'' is '''search''') and '''block_online_users''' (''type'' is '''block_''' and ''plugin'' is '''online_users''').

It is important to grasp that every block is now a discrete module type. This applies to all pluggable resources, so every, e.g., questiontype, authentication plugin, grade report is a separate module and will have its own language file and it's own directory for its help files. Not all plugin types define both language strings and help files but here is an example of what you might find for a pluggable resource that is included in core:

Description: questiontype plugin for multichoice
Module name: qtype_multichoice
Language strings (English): question/type/multichoice/lang/en_utf8/qtype_multichoice.php
Help files directory (English): question/type/multichoice/lang/en_utf8/help/qtype_multichoice/

All of the above must be in place for pluggable language and help strings to be a possibility for optional plugins.

NOTE: Module names cannot have numbers in them (only A-Z, a-z and underscore). This might be an issue to consider if you are moving from an existing architecture.

== Defining the search path(s) ==

The next step is to define the search locations for the plugin. This is only needed to define where the optional plugins will be installed, the standard help locations will be searched automatically. This is done by adding an entry to the array defined in the function '''places_to_search_for_lang_strings''' located in '''lib/moodlelib.php'''. This should be obvious from viewing the code but don't forget to include the underscore!

Some plugins define multiple locations for the same plugin type. For example, admin reports, course reports and quiz reports all have the plugin type '''report_'''. The code permits an array of different locations to be specified which are checked in turn.

Viewing this function will also show you what Moodle elements currently support language string searching. This varies somewhat from version to version of Moodle as new locations are added.

== Adding language support to a plugin ==

If you are a plugin writer and you didn't read the first part of this you just need to be aware that your plugin name needs to start with the generic type for the plugin. For example all questiontype plugins '''must''' be prefixed '''qtype_''', all authentication plugins '''auth_'''. Moodle uses this prefix to identify the language search path.

All that remains is now to add the language support to the optional plugin(s). This is done by creating a '''lang''' subdirectory in the plugin directory. The structure of the '''lang''' directory is then the same as the "main" language directory with one exception - the help directory name should '''not''' have the ''type_'' part of the module name (this might be a bug really!). Example...

Description: Drag & Drop optional question type
Module type: qtype_
Module name: qtype_dragdrop
Language file location (English): contrib/plugins/question/type/dragdrop/lang/en_utf8/qtype_dragdrop.php
Help file directory (English): contrib/plugins/question/type/dragdrop/lang/en_utf8/help/dragdrop/

(Note: the help file directory is called '''dragdrop''' in the plugin. Compare this with the multichoice question type in core where the help folder is '''qtype_multichoice''')

== See also ==

* [http://phpdocs.moodle.org/HEAD/default/string_manager.html PHPdocs for the string_manager class]

[[Category:Developer]]
[[Category:Language]]

Development:CVS for developers

2011-01-15T19:45:45Z

Howardsmiller:

'''NOTE: Moodle has now adopted Git for core development along with a new and evolving workflow. This document may no longer apply'''

'''CVS''' is the Concurrent Versioning System, a commonly-used way of managing source code for large software projects. CVS keeps all versions of all files so that nothing is ever lost, and usage by different people is tracked. It also provides ways to merge code if two or more people are working on the same file. All code and all versions are stored on a central server (in the case of Moodle, at cvs.moodle.org). The [http://cvsbook.red-bean.com/cvsbook.html CVS book] holds more information about CVS than you need.

If you just want to download Moodle using CVS to run a site, then you probably don't need this page - please see [[CVS for Administrators]] instead.

==Joining the project as a developer==

So, you've been offered CVS write access to help us develop and maintain Moodle! Welcome aboard!

To be able to write changes into [http://cvs.moodle.org/ Moodle's CVS archive], you first need to have an account on the server. Only trusted developers get these accounts. To request access, go to the "Apply for CVS Access" tab on the CVS page on Moodle.org (http://moodle.org/cvs). Tell us what modules you'd like to access (e.g. a language module), and why. You'll receive notification as soon as one of the core admins can authorise it. (Please be patient, but if you feel your application is languishing, message Martin D on moodle.org :) )

With that done, you should have all the permissions you need, so you just need to set up your machine and download the current source code so you can start working on it.

For the examples on this page, let's assume your username is '''myusername''' and your password is '''mypassword'''. Things are a lot easier if you use an SSH key to access the server, as you won't have to keep typing these in. Check [[Development:SSH_key | here]] for instructions on how to make one.

==CVS modules==

Within CVS, the word "modules" refers to separate collections of code. In Moodle we have the following modules within our repository:

* '''moodle''' - the main Moodle source code
* '''lang''' - all the language packs
* '''[[Development:contrib|contrib]]''' - user contributions and other assorted code in development
* '''mysql''' - a customised phpMyAdmin to plug into Moodle for database admin
* '''windows-cron''' - a small package that makes cron possible on Windows systems
* '''docs''' - various extra user-contributed documentation

Most people are working on the existing features in the moodle module, but many are also contributing new ideas in the contrib modules. Once code reaches a certain level of maturity in the contrib area, it can be migrated over into the main moodle tree.

==Basic CVS commands==

===CVS on Unix===

Moodle CVS uses ssh as a transport layer for security, so you will have to set a CVS_RSH environment variable in your Unix shell. It's best to put these commands in your .bashrc or .cshrc so you don't have to type it all the time:
setenv CVS_RSH ssh (for csh, tcsh etc)
export CVS_RSH=ssh (for sh, bash etc)

Next, you can check out the latest development version of Moodle using this (all one line). NOTE: Don't try to do run this first CVS command over an existing moodle installation: start fresh with a new directory!:
cvs -z3 -d:ext:myusername@cvs.moodle.org:/cvsroot/moodle co -P moodle

The command is similar for other CVS modules:
cvs -z3 -d:ext:myusername@cvs.moodle.org:/cvsroot/moodle co -P contrib

If you want to checkout a single plugin (attendance block as an example here) from contrib into the current directory, you can use:
cvs -z3 -d:ext:myusername@cvs.moodle.org:/cvsroot/moodle co -d attendance contrib/plugins/blocks/attendance

Note that you will be prompted for mypassword for each command unless you set up authorized keys. Read [[Development:SSH_key|SSH Keys]] for more details on how to set those up.

Now, you should have a new 'moodle' directory. You can rename it and move it around if you like. Go into it:
cd moodle

All the latest Moodle files should be in there. You can now change files in your copy. To compare your files and directories against the main CVS copy on the server use cvs diff, e.g.:
cvs diff -c config-dist.php
cvs diff -c lang

To fetch the latest updates from the server use:
cvs update -dP

To copy your new files back to the server you would do something like:
cd lang/ca
cvs commit

You will be prompted to add some comments (depends on your default text editor). Please write a meaningful, descriptive comment and '''always include the name of any tracker issues that talk about the issue you are fixing''' (eg '''MDL-XXXX''').

After that your changes will be sent to the CVS server and stored in the repository. Done!

To save more time you can put default arguments into a file called .cvsrc in your home directory. For example, mine contains:
diff -c
update -dP

Try 'cvs help' for more details ...

=== CVS on Mac OSX ===

You can follow the same instructions as for Unix (above) in a terminal window. However, the cvs command is not installed by default in an OSX. You first need to install the '''Xcode Tools'''. You should find this on your original installation disk. Failing that it can be downloaded (a fairly hefty download) from the [http://developer.apple.com/technology/tools.html Apple developer web site].

=== CVS on Windows ===

First, you need to download a completely fresh copy of Moodle using your developer account. (If you only want a private copy for local development, anonymous login will work too.)

1. Get [http://www.tortoisecvs.org TortoiseCVS] and install it, then reboot. TortoiseCVS works under Windows 95, 98, ME, NT, 2000, XP, and 2003. Vista is also supported, although some people report problems with UAC. (In the latter case you might resort to [http://www.syntevo.com/smartcvs/index.html SmartCVS].)

2. Find or create a new folder somewhere where you want Moodle to be downloaded to.

3. Right-mouse-click that folder and choose "CVS Checkout" from the menu. You should see a dialog box.

4. Copy this text into the CVSROOT field (using your own username!):

:ext:myusername@cvs.moodle.org:/cvsroot/moodle

5. Under the "Module" field, type "moodle" to get the latest development version of Moodle, "contrib" to get the contributions directory, or "mysql" to get the MySQL Admin module.

6. Press the button: "OK" and everything should be downloaded.

A dialog box should show all the files being downloaded, and after a while you should have a complete copy of Moodle. After this first checkout, you can fetch the latest updated files from the CVS server:

# Right-mouse-click on your Moodle folder (or any file) and select "CVS Update".
# Sit back and watch the logs scroll by. Take note of conflicts that may occur if your local code has changes that conflict with the incoming versions - you will need to edit these files and resolve the conflicts manually.

After modifying files (you will notice their icons change from green to red!), you can commit them back to the CVS server like this:

# Right-mouse-click on your Moodle folder (or any file) and select "CVS Commit...".
# In the dialog box, type a clear description of the changes you are committing. '''Always include the name of any tracker issues related to what you are fixing''' (eg '''MDL-XXXX''').
# Click "OK". Your changes will be sent to the server.
# If you create a folder, BE CAREFUL about using the "CVS Add" option as it will add the folder to CVS without requiring a commit. Once added, the folder cannot be removed from CVS even though it will be pruned so long as it is empty.

N.B. I had enormous headaches with the above settings until I changed from ext to ssh. This was using an ssh certificate on windows 2003 to both check out and commit code. Your mileage may vary, of course. [[User:Matt Gibson|Matt Gibson]] 12:52, 18 August 2008 (CDT)

=== CVS through your IDE ===

Will naturally depend on the IDE you choose to use so we do not give specific instructions here. For some IDEs, there are instructions elsewhere here. (E.g. [[Development:Setting_up_Eclipse|for Eclipse]].)

However, '''be warned''', we have noticed that when adding a new file to CVS using some IDEs (for example Eclipse), then by default they forcibly set the [http://ximbiot.com/cvs/manual/cvs-1.11.23/cvs_12.html#SEC101 CVS substitution mode] to -kk for ASCII files. In Moodle we like all ASCII files to be stored with the CVS default of -kkv, so if you use an IDE like this, please adjust its default.

If you are never likely to add a new file to CVS, you don't need to worry too much about the preceding paragraph. If you know something version control, you might think that -kk is better than -kkv, and in many ways you would be right. (For example it makes merging easier.) However, for the Moodle project, we use -kkv because it makes it easier to generate the [[Development:Unmerged_files|Unmerged files]] page, and because expanded $Id$ tags in the download packages makes it easier for people to make more specific bug reports.

==CVS commit messages==

Every commit you make to CVS should have a commit message. These can be invaluable. They are included in the automatic emails sent out whenever a change is made to Moodle, so they help other developers follow and review what is being changed; and they are very helpful when tyring to understand a piece of code. CVS will tell you who last changed each line of code, and when they did it. The commit comment (hopefully) tells you why.

A commit message should contain, in order:
* A couple of words indicating which part of moodle this change affects. For example 'forum backup', 'quiz attempting' or 'weblib'.
* A tracker issue id like MDL-12345. (If necessary, create an issue before committing, the only exception is for very minor typos.)
* A brief description of the problem you are fixing. (If you are feeling lazy, you may be able to get away with copying and pasting the issue summary from the tracker.)
* If it is not immediately obvious, a brief summary of why this change fixes the problem. If a longer description is necessary, you may also want to add more information to the tracker issue, or Moodle Docs, but the code changes + commit message should provide enough clues to how the fix works on their own.

Here is an example of a commit message from a simple change:

user selection: MDL-17072 Polishing the role assign page: Do processing
before print_header in line with best practice.

Actually, the ideal commit message would be a bit shorter than that. It is good if the first three items (area of Moodle, tracker id and brief description) will fit in the subject line of an email message.

Here is an example from a bigger commit (would it have been better if this could have been done as several smaller commits?):

role overrides: MDL-17070 Improve override roles page to match the recent
usability improvements on the assign page.

Including:
MDL-11529 When assigning/overriding roles, the dropdown for switching to
another role should have a number in brackets

MDL-16549 Should not be able to edit the permission associated with
moodle/site:doanything on any role.

Here is an example of a commit (from a while ago, which is why the issue number is in the wrong place) with some explanation of the change:

accesslib: get_user_by_capability() - Handle complex rolecap resolution

With this patch, get_user_by_capability() can handle the cases where
users have multiple role assignments to the same course, and PREVENTs
and PROHIBITs affect the rolecaps of this course.

Without stored procedures we cannot resolve this entirely on the
server side - so in the complex cases we do as much as we can on SQL,
and post-process the data on the PHP side, including SQL-style
pagination.

MDL-12452

===The CVS commits email list===

You can subscribe at http://lists.moodle.org/info/commits to this email list. You will then get an email every time someone commits a change to Moodle. This is a good way to keep track of what is going on, and also a good way to learn best-practice for CVS commit messages.

You probably want to set your mail client to automatically move messages from this list into a separate mail folder. You may not want to remain subscribed all the time, but when you are new to the project, it is a great way to do a bit of social-constructionist peer learning about our use of CVS.

==Working with branches==

This diagram shows how the main moodle module branches into different versions over time.

[[Image:Cvstree.png|CVS tree]]

To see all the current tags and branches that are available, use this command on any old file (such as index.php in the top moodle directory):
cvs status -v index.php

Some tagging guidelines:
* Tag and branch names should always be all upper-case.
* Tags and branches should ALWAYS be applied to the entire module (all of Moodle). Don't tag individual files or directories.
* We don't allow renaming of tags because people may be relying on them, so get them right the first time!

===Trunk development===

The Trunk of CVS is the main development version of Moodle. In CVS it is also known as the HEAD, or default branch.

Moodle developers try to keep this stable as possible, but as it usually contains new code it probably has bugs and small instabilities.

Every now and then we decide the product has enough features to make a release. At this time, the trunk is tagged with a MOODLE_XX_BETA tag (in case we ever want to roll back to that point) and a new branch is formed for the release, called MOODLE_XX_STABLE.

A Beta package is also released at this point - it's for testers who don't use CVS but want to test the latest features and report bugs.

===Stable branches for each release===

As soon as the stable branch MOODLE_XX_STABLE is created, development efforts will fork into two streams for a while. Some people may continue working on new features in the trunk for the next release, but most developers should be concentrating on using the current STABLE branch and fixing bugs that are found in it.

You can switch your local copy of Moodle to the STABLE version using the following command in Unix from the root directory:
cvs update -dP -r MOODLE_XX_STABLE

After that, all the commands described above will apply to that stable version. To return to the trunk version just issue:
cvs update -dPA

On Windows clients you should have a menu from which you can choose the branch.

Once the new STABLE branch really stabilises, a release can be declared. Packages are created for distribution and the branch will be tagged (by Martin Dougiamas) with a tag named: MOODLE_XXX

===Merging fixes===

All bug fixes in any STABLE branch should be merged back into the trunk so that they become available in future versions of Moodle. A floating tag called MOODLE_XX_MERGED needs to be maintained to keep track of the last merge. The procedure for such a merge is as follows (I'm using CVS on the Unix command line but the steps are the same for any CVS client):

[[Image:Merging.png|thumb|right|300px|This diagram summarises the process]]
1. I highly recommend keeping one checked out copy of each stable branch and the trunk/head version locally to make it easier to jump between them. Set them all up as virtual web sites on your development machine. I use directories like /moodle/18, /moodle/19 /moodle/dev etc.

2. Update to the latest stable version (I'll use XX in the example but it could be 18, 19 etc) for the relevant files, and do a cvs diff just to double-check exactly what you are checking in. Note you only need to update the files/directories you are working in, but sometimes it help to update everything anyway just to do a final check on the functionality using the web.

cd /moodle/XX/user
cvs update -dPA
cvs diff -c file1.php file2.php

3. If all looks OK, check in the fix to the stable branch. Make sure that the commit message contains the bug tracker ID (eg MDL-1111) and a decent description of your thoughts on the fix. If you don't specify a message in the command line, you'll be put into an editor to type one.

cvs commit -m "MDL-1234 Corrected a small typo in the user name field" file1.php file2.php

4. Go to the very latest trunk version and make sure it's up-to-date.

cd /moodle/dev/user
cvs update -dPA

5. Merge everything into your local copy of the trunk from your stable branch since the last merge. You can use the same sequence of (4) and (5) to merge the changes into other stable branches too (to backport the fix to the previous stable versions).

cvs update -kk -j MOODLE_XX_MERGED -j MOODLE_XX_STABLE file1.php file2.php

6. Carefully watch the update logs for conflicts, and fix every file that you see with a conflict. Afterwards, it may help to just run a diff to make sure the result is what you expected:

cvs diff -c file1.php file2.php

7. Check your merged local copy back into CVS trunk version

cvs commit -m "MDL-1234 Corrected a small typo in the user name field, merged from XX" file1.php file2.php

8. Go back to your branch version

cd /moodle/XX/user

9. Update the floating merge tag for the affected files (so that it matches MOODLE_XX_STABLE) so that this process can be repeated next time

cvs tag -F MOODLE_XX_MERGED file1.php file2.php

Finally, the values for $version in all the Moodle version.php files within the stable branch should not be updated at all if possible (except the last digit if absolutely necessary). The reason is that someone updating from a very stable version to the next very stable version could miss database upgrades that happened on the trunk.

In other words, if you have changes to the database schema to commit to a stable branch, please check with Martin Dougiamas, or one of the other core Moodle developers.

===Backporting===
Sometimes you fix something in a branch that needs to be "backported" to an earlier branch. This is often the case with security fixes. The procedure is exactly the same as described above, except you apply your changes backward instead of forward (to previous versions instead of HEAD). Here is a summary, using the steps described above. The scenario is that you have a fix in MOODLE_19_STABLE that needs backporting to MOODLE_18_STABLE, but NOT to HEAD (the problem you are fixing doesn't exist in HEAD):

cd /moodle/19/lib
cvs update -dPA
cvs diff -c file1.php file2.php

cvs commit -m "MDL-1234 Fixed major security hole" file1.php file2.php

cd /moodle/18/lib
cvs update -dPA

cvs update -kk -j MOODLE_19_MERGED -j MOODLE_19_STABLE file1.php file2.php
cvs diff -c file1.php file2.php

cvs commit -m "MDL-1234 Fixed major security hole, backported from 19" file1.php file2.php

When it comes to tagging, things change a little bit. You've now got changes in 18 and 19, both of which are stable releases, so need to be tagged as MERGED. You start with 18 (assuming you are still in that directory)

cvs tag -F MOODLE_18_MERGED file1.php file2.php

Then, you go and do the same for 19, ''regardless of whether or not the changes were merged into HEAD''. Of course, if the changes need to be merged into HEAD, you do that first. But if they don't, you still need to tag the modified files of each stable branch once your fixes are complete and tested:

cd /moodle/18/lib
cvs tag -F MOODLE_19_MERGED file1.php file2.php

===Merging fixes with TortoiseCVS===
Situation: we did a fix on MOODLE_19_STABLE. We modified one file for this fix. This fix needs to be done on Moodle 1.8 and trunk(HEAD). All following CVS instructions will be applied on the file that we changed.

1. Update to the latest stable versions (HEAD included)

Right click on the moodle folder
CVS update
OK

2. On your MOODLE19 branch: commit your fix

Right Click on the file
CVS commit
Enter a description: "MDL-XXXX bug fix description"
OK

3. On your HEAD repository: merge the changes

Right Click on the file
CVS>
Merge...
Start: MOODLE_19_MERGED
End : MOODLE_19_STABLE
OK

4. If the resulting file have some conflicts, TortoiseCVS displays a red square on the file icon. Edit the file with your text editor and resolve the conflicts.

5. Run a diff to make sure the result is what you expected

Right Click on the file
CVS Diff
OK

6. Commit the fix

Right Click on the file
CVS commit
Enter a description: "MDL-XXXX bug fix description, merged from 19"
OK

We've commit MOODLE_19_STABLE and trunk. It's now time to backport the change on MOODLE_18_STABLE.
On your MOODLE18 branch: reproduce step 3 to 6.

7. On your MOODLE19 branch: update the floating merge tag for the affected file

Right Click on the file
CVS>
Tag...
Tag: MOODLE_19_MERGED
Select 'Move existing tag'
OK

On your MOODLE18 branch: reproduce step 7 (with Tag: MOODLE_18_MERGED).

===Feature branches for large changes===

Occasionally, there may be a very large feature that needs to be checked in so several people can work on it, but it is too unstable to be included in the main development trunk.

In these cases a short-term branch can be created to work on the feature, and then merged back into the main trunk as soon as possible. An example called MOODLE_19_WIDGET branch can be seen in the above diagram.

If you need to do this for your new WIDGET feature, follow these steps:

1. Discuss with other developers to make sure it's necessary!

2. Make a new tag on the trunk (for all of moodle) called MOODLE_XX_WIDGET_PRE

cvs tag -R MOODLE_XX_WIDGET_PRE

3. Create your branch called MOODLE_XX_WIDGET

cvs tag -Rb MOODLE_XX_WIDGET

4. Work in that branch until the feature is reasonably stable. Commit as necessary.

cvs commit

5. When ready, merge the whole branch into the trunk, fix conflicts, commit it to the trunk and then abandon the branch.

cvs update -dPA
cvs update -kk -j MOODLE_XX_WIDGET
cvs commit

Good luck, be careful and have fun!

==Who on earth is ...==

Some of the people committing to the Moodle codebase have non-boring account names on the CVS server. If you are ever looking at a CVS commit, and wondering "who on earth is this purpleblob person?" This information is now available at: [http://moodle.org/mod/cvsadmin/view.php?cid=1 Moodle developers with write access].

==Tips and Hints==
* [http://moodle.org/mod/cvsadmin/ Change your password or SSH key] (click on "Update my developer information")
* [[Tracking Moodle CVS with git]]
* [http://moodle.org/mod/forum/discuss.php?d=34472 Merging Custom Moodle Code With Stable Releases]
* [[Unmerged files]]: To see if you've forgotten to merge any file.
* [http://ximbiot.com/cvs/manual/ CVS Manual]
* [[Development:contrib|Introduction to the '''contrib''' area of CVS]]

==See also==

* [http://tracker.moodle.org/browse/MDLSITE-193 "All developers should switch to using the cvs.moodle.org alias"]
* [[CVS for Administrators]]

[[Category:Developer| CVS for developers]]
[[Category:Developer tools| CVS for developers]]

[[es:CVS para desarrolladores]]
[[fr:CVS pour développeurs]]
[[pt:CVS_para_programadores]]

Upgrading

2011-01-14T15:58:15Z

Howardsmiller: /* Linux */

Moodle is designed to upgrade itself from one version to the next. The procedure is
# [[Site backup|Back up everything]].
# Replace the old version of the code with the new one.
# Visit the [[Site_administration_block#Notifications|administrator notifications]] link, which triggers Moodle to self-update.
These steps are explained in more detail below.

Sometimes there are specific considerations when upgrading to a particular version. Please refer to [[Upgrading to Moodle 1.6]], [[Upgrading to Moodle 1.8]], [[Upgrading to Moodle 1.9]] or [[Upgrading to Moodle 2.0]] if applicable. You also have to be more careful if you have installed additional plug-ins or customised the code.

See this tutorial if you are [http://ic.eflclasses.org/tutorials/howtoupgrademoodlewithcpanel.swf upgrading Moodle on cpanel]. It is a bit rough around the edges and is a little dated, but you should get the idea.

There is also a separate page about [[Ubuntu_Debian_Upgrades|upgrading Moodle if you installed it using the Ubuntu/Kubuntu/Debian package manager]].

__TOC__

When upgrading a Moodle installation you should follow these steps:

==Before you upgrade your site for real==

You are strongly advised to make a copy of your entire Moodle site onto another computer (see [[Moodle migration]]) and run the upgrade there to verify it will work.

==Check the requirements==
Spend some time re-reading the [[Installing Moodle | installation documentation]] and documentation for the new version. Check the system requirements for the target version you want to upgrade-to in ''Administration > Server > [[Environment]]''.
==Put your Site into Maintenance Mode==
Before you begin upgrading your site, you should put it into [[Maintenance_mode | Maintenance Mode]] to stop any non-admin users from logging in.

== Backup important data ==
See [[Site backup]] for more specific information.

There are three areas that should be backed up before any upgrade:
#Moodle software (For example, everything in server/htdocs/moodle)
#Moodle uploaded files (For example, server/moodledata)
#Moodle database (For example, the SQL or Progres database)

Experienced site administrators know that it is a best practice (a very good idea) to make a backup of any production system before a major upgrade. In fact, it is a good idea to automate your server to backup your Moodle installation daily. Most upgrades on sites that have used the standard Moodle packages (no contributed code and no little tweaks to the php files), will not have any major issues with the upgrade process.

:''TIP:'' One more time, "do not risk what you can not afford to lose": do regular backups, make sure it is really backed up and know how to restore a backup!

== Install the new Moodle software ==
Upgrading can be a simple process or a more complicated process. Sites that have not used contributed code and are migrating from say Moodle 1.x.1 to 1.x.3 '''should''' not have a problem. However, we still recommend that with any production server that you have made a successful backup of the MySQL database, the moodledata directory and the moodle program folders and files.

*Do not overwrite an old installation unless you know what you are doing ... sometimes old files can cause problems in new installations. Review the backup section above.

=== Standard install package ===
Having read the cautions about backups, download a copy of the standard install package. Here is a set of simple instructions for an average site.
*It is probably a good idea to use the [[Site administration block]]>Server>Maintenance mode to prevent user activity as the site upgrades.
*Having moved your old Moodle software program files to another location, unzip or unpack the upgrade file so that all new the Moodle software program files are in the location the old files used to be in on the server. Moodle will adjust SQL and [[Moodledata directory|moodledata]] if it needs to in the upgrade.
*Copy your old [[Configuration file|config.php file]] back to the new Moodle directory.
*If you had added any custom plugins or themes into your Moodle you can add them to the new code. It is important to check that you get the correct version for your new version of Moodle. You should check in the optional plugins database. Be particularly careful that you do not overwrite any code in the new version of Moodle. If you are upgrading to Moodle 2.0 or newer, note that all optional plugins and themes required a significant rewrite and most do not have 2.0 versions (yet).
*Use the notification link in the site administration to start the upgrade process. You will see a series of lines or screens indicating progress.
*After a successful upgrade, turn off the maintenance mode, so your users can get into the site.

=== Using a downloaded archive ===
In some installs, the site administrator may overwrite the Moodle code with a backup copy. Or create a new clean install copy of Moodle, then restore an archive (via a compressed file or parts of a saved set of Moodle code files and folders).

*Do not overwrite an old installation unless you know what you are doing ... sometimes old files can cause problems in new or "cleaned" installations. The best way is to rename the current Moodle code directory (for example rename "moodle" to "moodleold"), then unpack the new Moodle archive into the old location (for example, a new directory called "moodle").

====Linux====
mv moodle moodle.backup
tar xvzf moodle-1.1.tgz

Next, copy across your config.php, any other plugins such as custom themes, and your .htaccess file if you created one ('''check that optional/custom plugins are the correct version for your new Moodle first'''):

cp moodle.backup/config.php moodle
cp -pr moodle.backup/theme/mytheme moodle/theme/mytheme
cp -pr moodle.backup/mod/mymod moodle/mod/mymod

Don't forget to

sudo chown www-data moodle/config.php

if necessary.

where www-data is whatever user the Apache user is on your system. This is often 'apache' or 'www'.
You can find out by doing 'ls -l' in your /var/www/moodle folder (or wherever your moodle site is)
and then looking at the owner and group.

so you may see something like

ls -l
...lots of lines...
-rw-r--r-- 1 apache system 784 Jun 28 2007 config.php
...lots more lines...

so the owner is apache and the group is system.

To replicate this on your new system you can do 'chown apache:system config.php'

or to do a whole group do

chown apache:system ./*

and recursively

chown -R apache:system ./*

=== Using CVS ===

You can use CVS for updating or upgrading your Moodle.
First you need to do a CVS checkout in your (empty) Moodle root directory.

You can use any of our [[CVS_for_Administrators#CVS_Servers|CVS Mirror servers]]. Just replace '''SERVER.cvs.moodle.org''' in the instructions below with the name of the mirror server you chose!.

====For Linux servers====

To do a CVS checkout of Moodle, you first have to logon to the Moodle CVS server.

<nowiki>cvs -d:pserver:anonymous@SERVER.cvs.moodle.org:/cvsroot/moodle login</nowiki>
No password for anonymous, so just hit the Enter button.

Go to the directory where you want the Moodle root to come and type

<nowiki>cvs -z3 -d:pserver:anonymous@SERVER.cvs.moodle.org:/cvsroot/moodle co -r MOODLE_18_STABLE moodle</nowiki>
(where MOODLE_18_STABLE is the desired version)

To update, just go into the Moodle root directory and update to the new files:

cvs update -dP
To update to a new version type in the following and change 18 to whatever newest version upgrade number is
cvs -Q update -dP -r MOODLE_18_STABLE

Make sure you use the "d" parameter to create new directories if necessary, and the "P" parameter to prune empty directories.

====For Windows servers====

You can use Tortoise CVS to do the initial checkout and the updates.

If you have been editing Moodle files, watch the messages very closely for possible conflicts. All your customised themes and non-standard plugins will be untouched.

Do not forget to trigger the install process in the site administration block (see below).

== Finishing the upgrade ==

The last step is to trigger the upgrade processes within Moodle.

To do this just visit the [[Site administration block]] admin page (or ''<nowiki>http://example.com/moodle/admin</nowiki>'') and the "Notifications" link.

Moodle will automatically detect the new version and perform all the SQL database or file system upgrades that are necessary. If there is anything it can't do itself (very rare) then you will see messages telling you what you need to do.

Assuming all goes well (no error messages) then you can start using your new version of Moodle and enjoy the new features!

:''TIP:'' Use the site administration block>Server>Maintenance mode to prevent users from changing data during the upgrade.
:''TIP:'' If you are running a large scale Moodle site (e.g. have more tha 10,000+ courses and 40,000+ users), make sure that you do your own performance profiling testing. Post a thread or check the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum] and check [[Tracker]] for potential issues.

== Verify the upgrade (optional) ==

If you wish to confirm that the database definitions in the upgraded database match the definitions of a new, clean install (which they should) you might like to look at [[Verify Database Schema]].

==Upgrading more than one version==

In general, it is recommended to upgrade via the newest of each major version of Moodle, for example 1.7 -> 1.9. An exception to this is when upgrading from 1.5 or 1.6, when it is recommended that 1.7 and 1.8 are skipped, in other words upgrade 1.5 -> 1.6 -> 1.9. (The main reason for this recommendation is that the default roles settings obtained when upgrading to 1.7 are not ideal for 1.8 onwards, 1.8 has problems with groups, etc.)

==See also==

*[[Installing Moodle]]
*[[Installation FAQ]]
*[[Upgrading to Moodle 1.6]]
*[[Upgrading to Moodle 1.8]]
*[[Upgrading to Moodle 1.9]]
*[[Upgrading to Moodle 2.0]]
*[[Environment]]
*[[Git]] Version control and upgrading
*Moodle.org [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
*[http://ic.eflclasses.org/tutorials/howtoupgrademoodlewithcpanel.swf How to upgrade Moodle with cpanel tutorial] - screencasts of older Moodle/Cpanel install but useful (also, a very large file that will take some time to load).

Using Moodle.org forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=26731&parent=125858 Using cvs]
*[http://moodle.org/mod/forum/discuss.php?d=56915 Upgrading from 1.5.2 to 1.7]
*[http://moodle.org/mod/forum/discuss.php?d=56991 Upgrade nightmares.... any help appreciated]
*[http://moodle.org/mod/forum/discuss.php?d=62463 After upgrading i get "Your site may not be secure." msg]
*[http://moodle.org/mod/forum/discuss.php?d=104887 Best practices for QA]

[[Category:Installation]]

[[es:Actualización de moodle]]
[[fr:Mise à jour]]
[[ja:アップグレード]]
[[nl:Upgraden]]
[[zh:升级]]
[[pl:Aktualizacja]]
[[de:Aktualisierung von Moodle]]
[[ru:Обновление]]

Upgrading

2011-01-14T15:55:20Z

Howardsmiller: /* Standard install package */

Moodle is designed to upgrade itself from one version to the next. The procedure is
# [[Site backup|Back up everything]].
# Replace the old version of the code with the new one.
# Visit the [[Site_administration_block#Notifications|administrator notifications]] link, which triggers Moodle to self-update.
These steps are explained in more detail below.

Sometimes there are specific considerations when upgrading to a particular version. Please refer to [[Upgrading to Moodle 1.6]], [[Upgrading to Moodle 1.8]], [[Upgrading to Moodle 1.9]] or [[Upgrading to Moodle 2.0]] if applicable. You also have to be more careful if you have installed additional plug-ins or customised the code.

See this tutorial if you are [http://ic.eflclasses.org/tutorials/howtoupgrademoodlewithcpanel.swf upgrading Moodle on cpanel]. It is a bit rough around the edges and is a little dated, but you should get the idea.

There is also a separate page about [[Ubuntu_Debian_Upgrades|upgrading Moodle if you installed it using the Ubuntu/Kubuntu/Debian package manager]].

__TOC__

When upgrading a Moodle installation you should follow these steps:

==Before you upgrade your site for real==

You are strongly advised to make a copy of your entire Moodle site onto another computer (see [[Moodle migration]]) and run the upgrade there to verify it will work.

==Check the requirements==
Spend some time re-reading the [[Installing Moodle | installation documentation]] and documentation for the new version. Check the system requirements for the target version you want to upgrade-to in ''Administration > Server > [[Environment]]''.
==Put your Site into Maintenance Mode==
Before you begin upgrading your site, you should put it into [[Maintenance_mode | Maintenance Mode]] to stop any non-admin users from logging in.

== Backup important data ==
See [[Site backup]] for more specific information.

There are three areas that should be backed up before any upgrade:
#Moodle software (For example, everything in server/htdocs/moodle)
#Moodle uploaded files (For example, server/moodledata)
#Moodle database (For example, the SQL or Progres database)

Experienced site administrators know that it is a best practice (a very good idea) to make a backup of any production system before a major upgrade. In fact, it is a good idea to automate your server to backup your Moodle installation daily. Most upgrades on sites that have used the standard Moodle packages (no contributed code and no little tweaks to the php files), will not have any major issues with the upgrade process.

:''TIP:'' One more time, "do not risk what you can not afford to lose": do regular backups, make sure it is really backed up and know how to restore a backup!

== Install the new Moodle software ==
Upgrading can be a simple process or a more complicated process. Sites that have not used contributed code and are migrating from say Moodle 1.x.1 to 1.x.3 '''should''' not have a problem. However, we still recommend that with any production server that you have made a successful backup of the MySQL database, the moodledata directory and the moodle program folders and files.

*Do not overwrite an old installation unless you know what you are doing ... sometimes old files can cause problems in new installations. Review the backup section above.

=== Standard install package ===
Having read the cautions about backups, download a copy of the standard install package. Here is a set of simple instructions for an average site.
*It is probably a good idea to use the [[Site administration block]]>Server>Maintenance mode to prevent user activity as the site upgrades.
*Having moved your old Moodle software program files to another location, unzip or unpack the upgrade file so that all new the Moodle software program files are in the location the old files used to be in on the server. Moodle will adjust SQL and [[Moodledata directory|moodledata]] if it needs to in the upgrade.
*Copy your old [[Configuration file|config.php file]] back to the new Moodle directory.
*If you had added any custom plugins or themes into your Moodle you can add them to the new code. It is important to check that you get the correct version for your new version of Moodle. You should check in the optional plugins database. Be particularly careful that you do not overwrite any code in the new version of Moodle. If you are upgrading to Moodle 2.0 or newer, note that all optional plugins and themes required a significant rewrite and most do not have 2.0 versions (yet).
*Use the notification link in the site administration to start the upgrade process. You will see a series of lines or screens indicating progress.
*After a successful upgrade, turn off the maintenance mode, so your users can get into the site.

=== Using a downloaded archive ===
In some installs, the site administrator may overwrite the Moodle code with a backup copy. Or create a new clean install copy of Moodle, then restore an archive (via a compressed file or parts of a saved set of Moodle code files and folders).

*Do not overwrite an old installation unless you know what you are doing ... sometimes old files can cause problems in new or "cleaned" installations. The best way is to rename the current Moodle code directory (for example rename "moodle" to "moodleold"), then unpack the new Moodle archive into the old location (for example, a new directory called "moodle").

====Linux====
mv moodle moodle.backup
tar xvzf moodle-1.1.tgz

Next, copy across your config.php, any other plugins such as custom themes, and your .htaccess file if you created one:

cp moodle.backup/config.php moodle
cp -pr moodle.backup/theme/mytheme moodle/theme/mytheme
cp -pr moodle.backup/mod/mymod moodle/mod/mymod

Don't forget to

sudo chown www-data moodle/config.php

if necessary.

where www-data is whatever user the Apache user is on your system. This is often 'apache' or 'www'.
You can find out by doing 'ls -l' in your /var/www/moodle folder (or wherever your moodle site is)
and then looking at the owner and group.

so you may see something like

ls -l
...lots of lines...
-rw-r--r-- 1 apache system 784 Jun 28 2007 config.php
...lots more lines...

so the owner is apache and the group is system.

To replicate this on your new system you can do 'chown apache:system config.php'

or to do a whole group do

chown apache:system ./*

and recursively

chown -R apache:system ./*

=== Using CVS ===

You can use CVS for updating or upgrading your Moodle.
First you need to do a CVS checkout in your (empty) Moodle root directory.

You can use any of our [[CVS_for_Administrators#CVS_Servers|CVS Mirror servers]]. Just replace '''SERVER.cvs.moodle.org''' in the instructions below with the name of the mirror server you chose!.

====For Linux servers====

To do a CVS checkout of Moodle, you first have to logon to the Moodle CVS server.

<nowiki>cvs -d:pserver:anonymous@SERVER.cvs.moodle.org:/cvsroot/moodle login</nowiki>
No password for anonymous, so just hit the Enter button.

Go to the directory where you want the Moodle root to come and type

<nowiki>cvs -z3 -d:pserver:anonymous@SERVER.cvs.moodle.org:/cvsroot/moodle co -r MOODLE_18_STABLE moodle</nowiki>
(where MOODLE_18_STABLE is the desired version)

To update, just go into the Moodle root directory and update to the new files:

cvs update -dP
To update to a new version type in the following and change 18 to whatever newest version upgrade number is
cvs -Q update -dP -r MOODLE_18_STABLE

Make sure you use the "d" parameter to create new directories if necessary, and the "P" parameter to prune empty directories.

====For Windows servers====

You can use Tortoise CVS to do the initial checkout and the updates.

If you have been editing Moodle files, watch the messages very closely for possible conflicts. All your customised themes and non-standard plugins will be untouched.

Do not forget to trigger the install process in the site administration block (see below).

== Finishing the upgrade ==

The last step is to trigger the upgrade processes within Moodle.

To do this just visit the [[Site administration block]] admin page (or ''<nowiki>http://example.com/moodle/admin</nowiki>'') and the "Notifications" link.

Moodle will automatically detect the new version and perform all the SQL database or file system upgrades that are necessary. If there is anything it can't do itself (very rare) then you will see messages telling you what you need to do.

Assuming all goes well (no error messages) then you can start using your new version of Moodle and enjoy the new features!

:''TIP:'' Use the site administration block>Server>Maintenance mode to prevent users from changing data during the upgrade.
:''TIP:'' If you are running a large scale Moodle site (e.g. have more tha 10,000+ courses and 40,000+ users), make sure that you do your own performance profiling testing. Post a thread or check the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum] and check [[Tracker]] for potential issues.

== Verify the upgrade (optional) ==

If you wish to confirm that the database definitions in the upgraded database match the definitions of a new, clean install (which they should) you might like to look at [[Verify Database Schema]].

==Upgrading more than one version==

In general, it is recommended to upgrade via the newest of each major version of Moodle, for example 1.7 -> 1.9. An exception to this is when upgrading from 1.5 or 1.6, when it is recommended that 1.7 and 1.8 are skipped, in other words upgrade 1.5 -> 1.6 -> 1.9. (The main reason for this recommendation is that the default roles settings obtained when upgrading to 1.7 are not ideal for 1.8 onwards, 1.8 has problems with groups, etc.)

==See also==

*[[Installing Moodle]]
*[[Installation FAQ]]
*[[Upgrading to Moodle 1.6]]
*[[Upgrading to Moodle 1.8]]
*[[Upgrading to Moodle 1.9]]
*[[Upgrading to Moodle 2.0]]
*[[Environment]]
*[[Git]] Version control and upgrading
*Moodle.org [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
*[http://ic.eflclasses.org/tutorials/howtoupgrademoodlewithcpanel.swf How to upgrade Moodle with cpanel tutorial] - screencasts of older Moodle/Cpanel install but useful (also, a very large file that will take some time to load).

Using Moodle.org forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=26731&parent=125858 Using cvs]
*[http://moodle.org/mod/forum/discuss.php?d=56915 Upgrading from 1.5.2 to 1.7]
*[http://moodle.org/mod/forum/discuss.php?d=56991 Upgrade nightmares.... any help appreciated]
*[http://moodle.org/mod/forum/discuss.php?d=62463 After upgrading i get "Your site may not be secure." msg]
*[http://moodle.org/mod/forum/discuss.php?d=104887 Best practices for QA]

[[Category:Installation]]

[[es:Actualización de moodle]]
[[fr:Mise à jour]]
[[ja:アップグレード]]
[[nl:Upgraden]]
[[zh:升级]]
[[pl:Aktualizacja]]
[[de:Aktualisierung von Moodle]]
[[ru:Обновление]]

Verify Database Schema

2011-01-14T14:19:10Z

Howardsmiller:

If you have been upgrading your Moodle site over several versions, it is possible (likely even) that some differences may have crept in between the database table definitions (the "schema") in your database and the version you would get creating a new empty site. This happens because of small errors or oversights in the upgrade scripts. Most of these differences are not harmful, but some may cause strange or unexpected errors. For example, if a default value has been added to a field and this was not reflected in an upgrade script code that assumes the presence of the default may fail to work as expected.

The solution is after doing an upgrade (or, if your problem is that the upgrade fails, before) to compare the database schema of the "production" site to that of a newly created site (where no upgrades have been performed) using '''exactly''' the same code base. There are a number of ways of doing this, but this article outlines a simple way using the Unix command line.

* Complete the upgrade
* Generate the database schema from your recently upgraded site using the following command:
mysqldump -d -u root -p ''myproductiondb'' >production.schema
* Copy the code of your production database to a new (web accessible) location (this is important, it *must* be the same version)
* Create a new, empty database and moodledata area for the new site as per the [[Installation]] instructions
* Edit the config.php file to point at the new database and locations, or delete it and use the install script
* Run the install script to generate the (if applicable) config.php file and the database (admin and site values are not important)
* Generate the database schema from your new site using the following command:
mysqldump -d -u root -p ''mycleandb'' >clean.schema
* Run the following command to detect the differences
diff -u production.schema clean.schema >db.diff

You can now look at ''db.diff'' with your favorite editor to see the differences.

'''NOTE:''' The above obviously applies to MySQL databases. Other databases are likely to have a similar function to dump only the schema. For example PostgreSQL has the '''pg_dump''' command. The remainder of the discussion still applies.

==Interpreting the diff file==

Firstly here's a (real) example:

--
-- Table structure for table `mdl_backup_config`
@@ -129,11 +93,11 @@
DROP TABLE IF EXISTS `mdl_backup_config`;
CREATE TABLE `mdl_backup_config` (
- `id` int(10) unsigned NOT NULL auto_increment,
+ `id` bigint(10) unsigned NOT NULL auto_increment,
`name` varchar(255) NOT NULL default '',
`value` varchar(255) NOT NULL default '',
PRIMARY KEY (`id`),
- UNIQUE KEY `name` (`name`)
+ UNIQUE KEY `mdl_backconf_nam_uix` (`name`)
) ENGINE=MyISAM AUTO_INCREMENT=15 DEFAULT CHARSET=utf8 COMMENT='To store backup configuration variables';

The file may have lots of blocks of changes. The - lines show lines to be taken out and the + lines the ones to replace them (from the production to the clean). So here, the int has been replaced with a bigint and the key name changed. Both of these, technically, should have been changed at some point by upgrade scripts but have been missed. In this case they are unlikely to affect the operation of Moodle.

==Should I worry?==

Changes in field types (as long as they are compatible) and key name changes seem to be the common issues but '''should''' not cause problems. Things to look out for would be along the lines of missing fields and changes to default values.

If you are about to upgrade to Moodle 2.0 you should be more concerned. In order for the upgrade to proceed smoothly it is a very good idea to correct these problems.

== See also ==

* The missing indexes report in SiteAdmin->Misc->XMLDB editor->Check Indexes
* [http://moodle.org/mod/forum/view.php?id=45 Moodle Databases Forum]

[[Category:Administrator]]

[[de:Datenbank-Schema prüfen]]

Verify Database Schema

2011-01-14T14:18:28Z

Howardsmiller:

If you have been upgrading your Moodle site over several versions, it is possible (likely even) that some differences may have crept in between the database table definitions (the "schema") in your database and the version you would get creating a new empty site. This happens because of small errors or oversights in the upgrade scripts. Most of these differences are not harmful, but some may cause strange or unexpected errors. For example, if a default value has been added to a field and this was not reflected in an upgrade script code that assumes the presence of the default may fail to work as expected.

The solution is after doing an upgrade (or, if your problem is that the upgrade fails, before) to compare the database schema of the "production" site to that of a newly created site (where no upgrades have been performed) using '''exactly''' the same code base. There are a number of ways of doing this, but this article outlines a simple way using the Unix command line.

* Complete the upgrade
* Generate the database schema from your recently upgraded site using the following command:
mysqldump -d -u root -p ''myproductiondb'' >production.schema
* Copy the code of your production database to a new (web accessible) location (this is important, it *must* be the same version)
* Create a new, empty database and moodledata area for the new site as per the [[Installation]] instructions
* Edit the config.php file to point at the new database and locations, or delete it and use the install script
* Run the install script to generate the (if applicable) config.php file and the database (admin and site values are not important)
* Generate the database schema from your new site using the following command:
mysqldump -d -u root -p ''mycleandb'' >clean.schema
* Run the following command to detect the differences
diff -u production.schema clean.schema >db.diff

You can now look at ''db.diff'' with your favorite editor to see the differences.

==Interpreting the diff file==

Firstly here's a (real) example:

--
-- Table structure for table `mdl_backup_config`
@@ -129,11 +93,11 @@
DROP TABLE IF EXISTS `mdl_backup_config`;
CREATE TABLE `mdl_backup_config` (
- `id` int(10) unsigned NOT NULL auto_increment,
+ `id` bigint(10) unsigned NOT NULL auto_increment,
`name` varchar(255) NOT NULL default '',
`value` varchar(255) NOT NULL default '',
PRIMARY KEY (`id`),
- UNIQUE KEY `name` (`name`)
+ UNIQUE KEY `mdl_backconf_nam_uix` (`name`)
) ENGINE=MyISAM AUTO_INCREMENT=15 DEFAULT CHARSET=utf8 COMMENT='To store backup configuration variables';

The file may have lots of blocks of changes. The - lines show lines to be taken out and the + lines the ones to replace them (from the production to the clean). So here, the int has been replaced with a bigint and the key name changed. Both of these, technically, should have been changed at some point by upgrade scripts but have been missed. In this case they are unlikely to affect the operation of Moodle.

'''NOTE:''' The above obviously applies to MySQL databases. Other databases are likely to have a similar function to dump only the schema. For example PostgreSQL has the '''pg_dump''' command. The remainder of the discussion still applies.

==Should I worry?==

Changes in field types (as long as they are compatible) and key name changes seem to be the common issues but '''should''' not cause problems. Things to look out for would be along the lines of missing fields and changes to default values.

If you are about to upgrade to Moodle 2.0 you should be more concerned. In order for the upgrade to proceed smoothly it is a very good idea to correct these problems.

== See also ==

* The missing indexes report in SiteAdmin->Misc->XMLDB editor->Check Indexes
* [http://moodle.org/mod/forum/view.php?id=45 Moodle Databases Forum]

[[Category:Administrator]]

[[de:Datenbank-Schema prüfen]]

Talk:Verify Database Schema

2011-01-14T14:14:57Z

Howardsmiller:

This page seems to apply to MySQL databases only. What about other platforms such as Postgres and MSSQL?
Is it necessary to verify the database schemas on other database platforms?

--[[User:Luis de Vasconcelos|Luis de Vasconcelos]] 13:45, 14 January 2011 (UTC)

I'm going to say yes. The problem is caused by minor bugs in the upgrade scripts that don't exactly match the table creation xml. That will be just as likely for any database. --[[User:Howard Miller|Howard Miller]] 14:14, 14 January 2011 (UTC)

Verify Database Schema

2011-01-14T10:56:42Z

Howardsmiller: /* Should I worry? */

If you have been upgrading your Moodle site over several versions, it is possible (likely even) that some differences may have crept in between the database table definitions (the "schema") in your database and the version you would get creating a new empty site. This happens because of small errors or oversights in the upgrade scripts. Most of these differences are not harmful, but some may cause strange or unexpected errors. For example, if a default value has been added to a field and this was not reflected in an upgrade script code that assumes the presence of the default may fail to work as expected.

The solution is after doing an upgrade (or, if your problem is that the upgrade fails, before) to compare the database schema of the "production" site to that of a newly created site (where no upgrades have been performed) using '''exactly''' the same code base. There are a number of ways of doing this, but this article outlines a simple way using the Unix command line.

* Complete the upgrade
* Generate the database schema from your recently upgraded site using the following command:
mysqldump -d -u root -p ''myproductiondb'' >production.schema
* Copy the code of your production database to a new (web accessible) location (this is important, it *must* be the same version)
* Create a new, empty database and moodledata area for the new site as per the [[Installation]] instructions
* Edit the config.php file to point at the new database and locations, or delete it and use the install script
* Run the install script to generate the (if applicable) config.php file and the database (admin and site values are not important)
* Generate the database schema from your new site using the following command:
mysqldump -d -u root -p ''mycleandb'' >clean.schema
* Run the following command to detect the differences
diff -u production.schema clean.schema >db.diff

You can now look at ''db.diff'' with your favorite editor to see the differences.

==Interpreting the diff file==

Firstly here's a (real) example:

--
-- Table structure for table `mdl_backup_config`
@@ -129,11 +93,11 @@
DROP TABLE IF EXISTS `mdl_backup_config`;
CREATE TABLE `mdl_backup_config` (
- `id` int(10) unsigned NOT NULL auto_increment,
+ `id` bigint(10) unsigned NOT NULL auto_increment,
`name` varchar(255) NOT NULL default '',
`value` varchar(255) NOT NULL default '',
PRIMARY KEY (`id`),
- UNIQUE KEY `name` (`name`)
+ UNIQUE KEY `mdl_backconf_nam_uix` (`name`)
) ENGINE=MyISAM AUTO_INCREMENT=15 DEFAULT CHARSET=utf8 COMMENT='To store backup configuration variables';

The file may have lots of blocks of changes. The - lines show lines to be taken out and the + lines the ones to replace them (from the production to the clean). So here, the int has been replaced with a bigint and the key name changed. Both of these, technically, should have been changed at some point by upgrade scripts but have been missed. In this case they are unlikely to affect the operation of Moodle.

==Should I worry?==

Changes in field types (as long as they are compatible) and key name changes seem to be the common issues but '''should''' not cause problems. Things to look out for would be along the lines of missing fields and changes to default values.

If you are about to upgrade to Moodle 2.0 you should be more concerned. In order for the upgrade to proceed smoothly it is a very good idea to correct these problems.

== See also ==

* The missing indexes report in SiteAdmin->Misc->XMLDB editor->Check Indexes
* [http://moodle.org/mod/forum/view.php?id=45 Moodle Databases Forum]

[[Category:Administrator]]

[[de:Datenbank-Schema prüfen]]

Talk:Branch structures

2011-01-11T15:56:27Z

Howardsmiller: New page: This needs some work to make any sense. It randomly uses notation like B1, V1 etc. without any explanation of what those codes mean --~~~~

This needs some work to make any sense. It randomly uses notation like B1, V1 etc. without any explanation of what those codes mean --[[User:Howard Miller|Howard Miller]] 15:56, 11 January 2011 (UTC)

Export questions

2011-01-04T11:23:19Z

Howardsmiller: /* Process */

Questions may be exported from the [[Quiz module]] and the [[Question bank]] in any one of 4 formats:

* [[GIFT format]]
* [[Moodle XML format]]
* [[IMS QTI 2.0 format]]
* [[XHTML format]]

==Process==
*Select the export tab.
[[Image:Question bank export.png|thumb|center|Export tab in Question bank]]
*Select the output type required for the exported file.
*Use the pulldown menu to select the question category you want to export
*Check if you want the category name to exported and/or the context to be included. This only applies to some formats and is used to restore this information on import.
*Click on the export questions to file button
*The exported questions will be listed to the screen for confirmation.
[[Image:Question bank Exported questions.png|thumb|center|Exported questions screen]]
*You are invited to download the file to your computer.

*The file has been saved in your course files (course admin block), backup>quiz.

==Example uses of exported files==
*GIFT and Moodle XML formats can be imported into the [[Lesson module]] And [[Question bank]] via [[Import questions|an import question process]].
*Exported question files on one server, can be imported into another Moodle site/server
*GIFT and Moodle XML formats can be tweaked to create word processing or spreadsheet documents suitable for paper tests or vetting.
*In case you want to convert your Moodle XML file into text format upload XML to [http://moodle.heroku.com http://moodle.heroku.com]. It automatically generates *.txt with your questions

==See also==
*[http://moodle.heroku.com Moodle XML Converter] to generate in and from XML.
*[http://www.moodle2word.net Website for converting Moodle Questions into tables in a Microsoft Word file, and vice versa].

[[Category:Questions]]

[[de:Fragen exportieren]]
[[eu:Galderak_esportatu]]
[[fr:Exporter des questions]]
[[ja:問題のエクスポート]]

Development:Development hints and tips

2010-12-23T09:56:14Z

Howardsmiller: /* Use a Version Control system */

{{Work in progress}}

There is a great deal of development experience amongst the Moodle developers. This page is some general hints and tips that may help people starting out in PHP and Moodle development. These apply as much to people writing their own plugins as core developers.

== Avoid writing code in the first place ==

Always take the trouble to find if there is another (existing) way to do what you need. Failing that, does a plugin or option already exist. Failing that, does something exist that you can modify. Failing that, is there a library (or libraries) that exist to reduce your effort. Lastly write the code yourself. Existing, tested code is always to be preferred - more so if it has an extensive user base.

== Follow the Coding Guidelines ==

Moodle has a well developed set of [[Development:Coding|Coding Guidelines]]. Read them and follow them. It's surprising how many custom plugins for Moodle do not. It instantly prevents your code from being incorporated in core Moodle.

Pay particular attention to the security information. A basic understanding of security in a web development environment is no longer optional. If you don't know what an XSS attack or an SQL injection are then you need to find out.

== When in Rome, do like the Romans ==

The Coding Guidelines do not describe every possible situation. When you find yourself in that situation, try to follow the example of how things are done in other parts of Moodle. Just because Moodle is not written the way you would do it if you were starting from scratch does not matter. In a large project like Moodle, it is more important to keep the code consistent than it is to satisfy your personal prejudices about how code should be. That makes it easier to maintain the code, and if you start writing Moodle-style code, you will find it easier to understand the other bits of Moodle code you look at.

Of course, some parts of Moodle are just badly written. You should not copy what is done in those places. ;-) When looking for examples to follow, try to find code that has been written recently by one of the reliable core developers.

Getting involved in a large Open Source project can be a bit of a culture shock if you are not used to it. Lots of advice (and, sometimes, constructive criticism) is readily available. Don't be afraid to ask - that's what the General Developer Forum is for.

== Use a Version Control system ==

If you are developing without a version control system then you are doing it wrong. The benefits run well beyond just being able to keep past versions of your code. Moodle currently uses CVS for core development but this is probably a poor (out of date) choice for a new project. Moodle uses [[Development:Git tips|Git]] for developing so it makes sense to learn it. This is a powerful distributed system and does take a bit of getting your head around but the effort is worth it.

== Find an editor or IDE that works for you and learn it properly ==

There are many different development platforms from complex Integrated Development Environments (IDEs) to simple editors and command line tools. Choose something that works for you and then take the trouble to learn how to use it properly.

Find the editor's customisation options and make it fit in with Moodle's coding guidelines - example, most editors can be persuaded to use the correct number of spaces (4 in Moodle's case) rather than the tab character.

== Comment effectively ==

Don't be shy about putting comments in code. If the code deserves a blank line it probably deserves a comment. It's obvious what the code does now but it won't be in six months.

== KISS (Keep It Simple Stupid) ==

Albert Einstein didn't ''actually'' say "Everything should be made as simple as possible, but no simpler" but it would still have been good advice if he had. Take the trouble to come up with the simplest solution to the problem at hand. Resist the temptation to add code for things that you ''might'' need in the future or ''might'' be required one day. They usually never happen and you can always change the code later if requirements change. For example, don't use some insanely complex object factory when old-fashioned procedural programming will do. Don't use old-fashioned procedural programming when a class-hierarchy models the real-world problem more intuitively. Avoid complex abstractions where they are not actually needed to get the job done. Any additional code increases the risk of bugs, security problems and maintenance issues in the future.

== Use good variable and function names ==

It should be easy and obvious to pick a name for a variable or a function. If it isn't you are either trying to make that function too complicated (simplify and break it up) or you haven't fully understood what you are trying to do (another cup of coffee?). Names should always say what they are for or what they do - plainly.

== Pretty code is good code ==

Seriously! Code that is well laid out and easy to read is easy to debug and to modify. Make the effort to lay out code so it looks good and is easy to read through. Don't be afraid to break something nasty into several lines so that it reads well. It's tempting to make one line of code do something incredibly complex but you won't feel so clever when you can't remember how it works.

== Write Plugins. Use APIs ==

Always, when developing custom features, write a standard plugin in preference to modifying core code. Even if you have to compromise the functionality a bit. Most Moodle plugin structures are able to easily create database structures, handle role capabilities, define language files and ease future updates. Furthermore, the end result can all be delivered in one simple zip file. It doesn't rely on one particular build of Moodle either. These are real and big advantages. A core code patch is only guaranteed to work with the exact build it was written with, it probably won't survive upgrades and patches are notoriously difficult to apply properly - even for experienced developers. If in doubt look at blocks - you can do an awful lot with a block (even if it's never actually added as a visible block). Blocks are reasonably easy to understand and to develop, too.

Similarly, take the trouble to investigate existing Moodle APIs and library calls. Your code will last longer and be more reliable.

== Separate out functionality ==

Or... don't muddle up the user interface with the database access and other logic. For example, alarm bells should ring if you are writing functions like '''get_data_and_display()'''. It is a much better idea to write '''get_data()''' and then '''display_data()'''. The effort is little or no different, however, the end result is often easier to follow and (say) if someone asks you to dump the data to Excel rather than display it the latter method saves you a costly refactor. Even if you are not writing functions and your logic is all on one page try to split things into logical blocks - read the input, THEN do the calculations and database access, THEN display the output. It will be easier to refactor or to modify.

== Don't Make Me Think ==

It's actually a title of a book by Steve Krug (and it should be obligatory reading for all web designers), however, the point is really about Usability. Usability is hard but you still have to try. Don't make your users have to think. Good documentation is important but it's hard to keep it up to date and it's a partial failure if someone has to resort to reading it. In particular, be quite clear that ordinary Moodle users don't care about clever implementation or super flexibility. Anything that complicates the job of getting effective learning materials to students is "a bad thing". Anything that in the name of adding flexibility or functionality makes an ordinary user's job more complex is a regression. If something must be done then the code must do it - do not burden the user.

Force yourself to think like a user and not a programmer. A clever, elegant solution to a programming problem is not guaranteed to result in a feature that is simple and intuitive to use. Look at the forums. If lots of people are having trouble using a feature then you need to consider if the feature is doing the job well enough.

It should be hard (or even better impossible) for users to break things. The greatest invention ever was the undo button - it doesn't only protect the user against mistakes it allows them to safely experiment. Users don't learn to use software by reading the manual - they experiment and guess. Make it easy for them.

There's some guidelines (currently under development) in [[Development:Moodle User Interface Guidelines|User Interface Guidelines]]

== Let the database do the grunt work ==

If there's a choice let the database do the work of searches. Especially if multiple tables are involved. It's what it was designed to do. It can be tempting, especially if your SQL knowledge isn't too good, to tie together multiple database queries with PHP loops and the like. Always consider using a single database call instead. Always try to use the basic Moodle database API functions before writing custom SQL (portability!).

Having said all that, optimising databases (especially when datasets get large) is a subject in itself. Nearly all web development involves database interactions so even basic db admin skills are very valuable and worthwhile acquiring.

== Generate helpful error messages ==

If you generate an error message, consider if it 'really' helps the user fix the problem. Be as specific as possible. If you can give information that will help resolve the problem rather than just say it happened then do so. BUT... you also have to consider security. Don't give away information that might help a hacker. You might want to consider debugging level (is it on?) and/or who the user is (you might give an administrator more information).

You should also try to trap as many possible errors as possible. If a function returns a fail condition then you would need to have a very good reason not to check it. This helps avoid the highly unpopular "white screen of death".

Add extra debugging code (call ''debugging()'' )if you think it might help. This is especially true for functions that have complex configuration or external dependencies (i.e. lots that can go wrong).

Never write an error message that looks something like "An unknown error occurred". You might as well not bother as this doesn't help anybody fix the problem.

== Turn on Debugging and fix those notices and warnings ==

If you get PHP warnings or notices when [[Debugging]] is switched on the problem is '''not''' that debugging has been left on, the problem is that there are bugs in your code. There is no excuse for not checking for and then fixing notices and warnings. To not do so is shoddy at best.

== Expand Moodle Docs ==

If something you want to do isn't documented (or isn't documented well or fully) and you figure it out - document it. Don't write it in your notebook or your company's closed Wiki, put it in the docs here. It's there for you next time and for everyone else as well.

== More tips please ==
(add your own!)

[[Category:Developer]]

Development:Development hints and tips

2010-12-23T09:52:14Z

Howardsmiller: /* Generate helpful error messages */

{{Work in progress}}

There is a great deal of development experience amongst the Moodle developers. This page is some general hints and tips that may help people starting out in PHP and Moodle development. These apply as much to people writing their own plugins as core developers.

== Avoid writing code in the first place ==

Always take the trouble to find if there is another (existing) way to do what you need. Failing that, does a plugin or option already exist. Failing that, does something exist that you can modify. Failing that, is there a library (or libraries) that exist to reduce your effort. Lastly write the code yourself. Existing, tested code is always to be preferred - more so if it has an extensive user base.

== Follow the Coding Guidelines ==

Moodle has a well developed set of [[Development:Coding|Coding Guidelines]]. Read them and follow them. It's surprising how many custom plugins for Moodle do not. It instantly prevents your code from being incorporated in core Moodle.

Pay particular attention to the security information. A basic understanding of security in a web development environment is no longer optional. If you don't know what an XSS attack or an SQL injection are then you need to find out.

== When in Rome, do like the Romans ==

The Coding Guidelines do not describe every possible situation. When you find yourself in that situation, try to follow the example of how things are done in other parts of Moodle. Just because Moodle is not written the way you would do it if you were starting from scratch does not matter. In a large project like Moodle, it is more important to keep the code consistent than it is to satisfy your personal prejudices about how code should be. That makes it easier to maintain the code, and if you start writing Moodle-style code, you will find it easier to understand the other bits of Moodle code you look at.

Of course, some parts of Moodle are just badly written. You should not copy what is done in those places. ;-) When looking for examples to follow, try to find code that has been written recently by one of the reliable core developers.

Getting involved in a large Open Source project can be a bit of a culture shock if you are not used to it. Lots of advice (and, sometimes, constructive criticism) is readily available. Don't be afraid to ask - that's what the General Developer Forum is for.

== Use a Version Control system ==

If you are developing without a version control system then you are doing it wrong. The benefits run well beyond just being able to keep past versions of your code. Moodle currently uses CVS for core development but this is probably a poor (out of date) choice for a new project. Moodle will soon be using [[Development:Git tips|Git]]. This is a powerful distributed system and does take a bit of getting your head around but the effort is worth it.

== Find an editor or IDE that works for you and learn it properly ==

There are many different development platforms from complex Integrated Development Environments (IDEs) to simple editors and command line tools. Choose something that works for you and then take the trouble to learn how to use it properly.

Find the editor's customisation options and make it fit in with Moodle's coding guidelines - example, most editors can be persuaded to use the correct number of spaces (4 in Moodle's case) rather than the tab character.

== Comment effectively ==

Don't be shy about putting comments in code. If the code deserves a blank line it probably deserves a comment. It's obvious what the code does now but it won't be in six months.

== KISS (Keep It Simple Stupid) ==

Albert Einstein didn't ''actually'' say "Everything should be made as simple as possible, but no simpler" but it would still have been good advice if he had. Take the trouble to come up with the simplest solution to the problem at hand. Resist the temptation to add code for things that you ''might'' need in the future or ''might'' be required one day. They usually never happen and you can always change the code later if requirements change. For example, don't use some insanely complex object factory when old-fashioned procedural programming will do. Don't use old-fashioned procedural programming when a class-hierarchy models the real-world problem more intuitively. Avoid complex abstractions where they are not actually needed to get the job done. Any additional code increases the risk of bugs, security problems and maintenance issues in the future.

== Use good variable and function names ==

It should be easy and obvious to pick a name for a variable or a function. If it isn't you are either trying to make that function too complicated (simplify and break it up) or you haven't fully understood what you are trying to do (another cup of coffee?). Names should always say what they are for or what they do - plainly.

== Pretty code is good code ==

Seriously! Code that is well laid out and easy to read is easy to debug and to modify. Make the effort to lay out code so it looks good and is easy to read through. Don't be afraid to break something nasty into several lines so that it reads well. It's tempting to make one line of code do something incredibly complex but you won't feel so clever when you can't remember how it works.

== Write Plugins. Use APIs ==

Always, when developing custom features, write a standard plugin in preference to modifying core code. Even if you have to compromise the functionality a bit. Most Moodle plugin structures are able to easily create database structures, handle role capabilities, define language files and ease future updates. Furthermore, the end result can all be delivered in one simple zip file. It doesn't rely on one particular build of Moodle either. These are real and big advantages. A core code patch is only guaranteed to work with the exact build it was written with, it probably won't survive upgrades and patches are notoriously difficult to apply properly - even for experienced developers. If in doubt look at blocks - you can do an awful lot with a block (even if it's never actually added as a visible block). Blocks are reasonably easy to understand and to develop, too.

Similarly, take the trouble to investigate existing Moodle APIs and library calls. Your code will last longer and be more reliable.

== Separate out functionality ==

Or... don't muddle up the user interface with the database access and other logic. For example, alarm bells should ring if you are writing functions like '''get_data_and_display()'''. It is a much better idea to write '''get_data()''' and then '''display_data()'''. The effort is little or no different, however, the end result is often easier to follow and (say) if someone asks you to dump the data to Excel rather than display it the latter method saves you a costly refactor. Even if you are not writing functions and your logic is all on one page try to split things into logical blocks - read the input, THEN do the calculations and database access, THEN display the output. It will be easier to refactor or to modify.

== Don't Make Me Think ==

It's actually a title of a book by Steve Krug (and it should be obligatory reading for all web designers), however, the point is really about Usability. Usability is hard but you still have to try. Don't make your users have to think. Good documentation is important but it's hard to keep it up to date and it's a partial failure if someone has to resort to reading it. In particular, be quite clear that ordinary Moodle users don't care about clever implementation or super flexibility. Anything that complicates the job of getting effective learning materials to students is "a bad thing". Anything that in the name of adding flexibility or functionality makes an ordinary user's job more complex is a regression. If something must be done then the code must do it - do not burden the user.

Force yourself to think like a user and not a programmer. A clever, elegant solution to a programming problem is not guaranteed to result in a feature that is simple and intuitive to use. Look at the forums. If lots of people are having trouble using a feature then you need to consider if the feature is doing the job well enough.

It should be hard (or even better impossible) for users to break things. The greatest invention ever was the undo button - it doesn't only protect the user against mistakes it allows them to safely experiment. Users don't learn to use software by reading the manual - they experiment and guess. Make it easy for them.

There's some guidelines (currently under development) in [[Development:Moodle User Interface Guidelines|User Interface Guidelines]]

== Let the database do the grunt work ==

If there's a choice let the database do the work of searches. Especially if multiple tables are involved. It's what it was designed to do. It can be tempting, especially if your SQL knowledge isn't too good, to tie together multiple database queries with PHP loops and the like. Always consider using a single database call instead. Always try to use the basic Moodle database API functions before writing custom SQL (portability!).

Having said all that, optimising databases (especially when datasets get large) is a subject in itself. Nearly all web development involves database interactions so even basic db admin skills are very valuable and worthwhile acquiring.

== Generate helpful error messages ==

If you generate an error message, consider if it 'really' helps the user fix the problem. Be as specific as possible. If you can give information that will help resolve the problem rather than just say it happened then do so. BUT... you also have to consider security. Don't give away information that might help a hacker. You might want to consider debugging level (is it on?) and/or who the user is (you might give an administrator more information).

You should also try to trap as many possible errors as possible. If a function returns a fail condition then you would need to have a very good reason not to check it. This helps avoid the highly unpopular "white screen of death".

Add extra debugging code (call ''debugging()'' )if you think it might help. This is especially true for functions that have complex configuration or external dependencies (i.e. lots that can go wrong).

Never write an error message that looks something like "An unknown error occurred". You might as well not bother as this doesn't help anybody fix the problem.

== Turn on Debugging and fix those notices and warnings ==

If you get PHP warnings or notices when [[Debugging]] is switched on the problem is '''not''' that debugging has been left on, the problem is that there are bugs in your code. There is no excuse for not checking for and then fixing notices and warnings. To not do so is shoddy at best.

== Expand Moodle Docs ==

If something you want to do isn't documented (or isn't documented well or fully) and you figure it out - document it. Don't write it in your notebook or your company's closed Wiki, put it in the docs here. It's there for you next time and for everyone else as well.

== More tips please ==
(add your own!)

[[Category:Developer]]

Development:Development hints and tips

2010-12-23T09:50:41Z

Howardsmiller: /* Generate helpful error messages */

{{Work in progress}}

There is a great deal of development experience amongst the Moodle developers. This page is some general hints and tips that may help people starting out in PHP and Moodle development. These apply as much to people writing their own plugins as core developers.

== Avoid writing code in the first place ==

Always take the trouble to find if there is another (existing) way to do what you need. Failing that, does a plugin or option already exist. Failing that, does something exist that you can modify. Failing that, is there a library (or libraries) that exist to reduce your effort. Lastly write the code yourself. Existing, tested code is always to be preferred - more so if it has an extensive user base.

== Follow the Coding Guidelines ==

Moodle has a well developed set of [[Development:Coding|Coding Guidelines]]. Read them and follow them. It's surprising how many custom plugins for Moodle do not. It instantly prevents your code from being incorporated in core Moodle.

Pay particular attention to the security information. A basic understanding of security in a web development environment is no longer optional. If you don't know what an XSS attack or an SQL injection are then you need to find out.

== When in Rome, do like the Romans ==

The Coding Guidelines do not describe every possible situation. When you find yourself in that situation, try to follow the example of how things are done in other parts of Moodle. Just because Moodle is not written the way you would do it if you were starting from scratch does not matter. In a large project like Moodle, it is more important to keep the code consistent than it is to satisfy your personal prejudices about how code should be. That makes it easier to maintain the code, and if you start writing Moodle-style code, you will find it easier to understand the other bits of Moodle code you look at.

Of course, some parts of Moodle are just badly written. You should not copy what is done in those places. ;-) When looking for examples to follow, try to find code that has been written recently by one of the reliable core developers.

Getting involved in a large Open Source project can be a bit of a culture shock if you are not used to it. Lots of advice (and, sometimes, constructive criticism) is readily available. Don't be afraid to ask - that's what the General Developer Forum is for.

== Use a Version Control system ==

If you are developing without a version control system then you are doing it wrong. The benefits run well beyond just being able to keep past versions of your code. Moodle currently uses CVS for core development but this is probably a poor (out of date) choice for a new project. Moodle will soon be using [[Development:Git tips|Git]]. This is a powerful distributed system and does take a bit of getting your head around but the effort is worth it.

== Find an editor or IDE that works for you and learn it properly ==

There are many different development platforms from complex Integrated Development Environments (IDEs) to simple editors and command line tools. Choose something that works for you and then take the trouble to learn how to use it properly.

Find the editor's customisation options and make it fit in with Moodle's coding guidelines - example, most editors can be persuaded to use the correct number of spaces (4 in Moodle's case) rather than the tab character.

== Comment effectively ==

Don't be shy about putting comments in code. If the code deserves a blank line it probably deserves a comment. It's obvious what the code does now but it won't be in six months.

== KISS (Keep It Simple Stupid) ==

Albert Einstein didn't ''actually'' say "Everything should be made as simple as possible, but no simpler" but it would still have been good advice if he had. Take the trouble to come up with the simplest solution to the problem at hand. Resist the temptation to add code for things that you ''might'' need in the future or ''might'' be required one day. They usually never happen and you can always change the code later if requirements change. For example, don't use some insanely complex object factory when old-fashioned procedural programming will do. Don't use old-fashioned procedural programming when a class-hierarchy models the real-world problem more intuitively. Avoid complex abstractions where they are not actually needed to get the job done. Any additional code increases the risk of bugs, security problems and maintenance issues in the future.

== Use good variable and function names ==

It should be easy and obvious to pick a name for a variable or a function. If it isn't you are either trying to make that function too complicated (simplify and break it up) or you haven't fully understood what you are trying to do (another cup of coffee?). Names should always say what they are for or what they do - plainly.

== Pretty code is good code ==

Seriously! Code that is well laid out and easy to read is easy to debug and to modify. Make the effort to lay out code so it looks good and is easy to read through. Don't be afraid to break something nasty into several lines so that it reads well. It's tempting to make one line of code do something incredibly complex but you won't feel so clever when you can't remember how it works.

== Write Plugins. Use APIs ==

Always, when developing custom features, write a standard plugin in preference to modifying core code. Even if you have to compromise the functionality a bit. Most Moodle plugin structures are able to easily create database structures, handle role capabilities, define language files and ease future updates. Furthermore, the end result can all be delivered in one simple zip file. It doesn't rely on one particular build of Moodle either. These are real and big advantages. A core code patch is only guaranteed to work with the exact build it was written with, it probably won't survive upgrades and patches are notoriously difficult to apply properly - even for experienced developers. If in doubt look at blocks - you can do an awful lot with a block (even if it's never actually added as a visible block). Blocks are reasonably easy to understand and to develop, too.

Similarly, take the trouble to investigate existing Moodle APIs and library calls. Your code will last longer and be more reliable.

== Separate out functionality ==

Or... don't muddle up the user interface with the database access and other logic. For example, alarm bells should ring if you are writing functions like '''get_data_and_display()'''. It is a much better idea to write '''get_data()''' and then '''display_data()'''. The effort is little or no different, however, the end result is often easier to follow and (say) if someone asks you to dump the data to Excel rather than display it the latter method saves you a costly refactor. Even if you are not writing functions and your logic is all on one page try to split things into logical blocks - read the input, THEN do the calculations and database access, THEN display the output. It will be easier to refactor or to modify.

== Don't Make Me Think ==

It's actually a title of a book by Steve Krug (and it should be obligatory reading for all web designers), however, the point is really about Usability. Usability is hard but you still have to try. Don't make your users have to think. Good documentation is important but it's hard to keep it up to date and it's a partial failure if someone has to resort to reading it. In particular, be quite clear that ordinary Moodle users don't care about clever implementation or super flexibility. Anything that complicates the job of getting effective learning materials to students is "a bad thing". Anything that in the name of adding flexibility or functionality makes an ordinary user's job more complex is a regression. If something must be done then the code must do it - do not burden the user.

Force yourself to think like a user and not a programmer. A clever, elegant solution to a programming problem is not guaranteed to result in a feature that is simple and intuitive to use. Look at the forums. If lots of people are having trouble using a feature then you need to consider if the feature is doing the job well enough.

It should be hard (or even better impossible) for users to break things. The greatest invention ever was the undo button - it doesn't only protect the user against mistakes it allows them to safely experiment. Users don't learn to use software by reading the manual - they experiment and guess. Make it easy for them.

There's some guidelines (currently under development) in [[Development:Moodle User Interface Guidelines|User Interface Guidelines]]

== Let the database do the grunt work ==

If there's a choice let the database do the work of searches. Especially if multiple tables are involved. It's what it was designed to do. It can be tempting, especially if your SQL knowledge isn't too good, to tie together multiple database queries with PHP loops and the like. Always consider using a single database call instead. Always try to use the basic Moodle database API functions before writing custom SQL (portability!).

Having said all that, optimising databases (especially when datasets get large) is a subject in itself. Nearly all web development involves database interactions so even basic db admin skills are very valuable and worthwhile acquiring.

== Generate helpful error messages ==

If you generate an error message, consider if it 'really' helps the user fix the problem. Be as specific as possible. If you can give information that will help resolve the problem rather than just say it happened then do so. BUT... you also have to consider security. Don't give away information that might help a hacker. You might want to consider debugging level (is it on?) and/or who the user is (you might give an administrator more information).

You should also try to trap as many possible errors as possible. If a function returns a fail condition then you would need to have a very good reason not to check it. This helps avoid the highly unpopular "white screen of death".

Add extra debugging code (call ''debugging()'' )if you think it might help. This is especially true for functions that have complex configuration or external dependencies (i.e. lots that can go wrong).

== Turn on Debugging and fix those notices and warnings ==

If you get PHP warnings or notices when [[Debugging]] is switched on the problem is '''not''' that debugging has been left on, the problem is that there are bugs in your code. There is no excuse for not checking for and then fixing notices and warnings. To not do so is shoddy at best.

== Expand Moodle Docs ==

If something you want to do isn't documented (or isn't documented well or fully) and you figure it out - document it. Don't write it in your notebook or your company's closed Wiki, put it in the docs here. It's there for you next time and for everyone else as well.

== More tips please ==
(add your own!)

[[Category:Developer]]

Talk:Moodle 2.0 release notes

2010-12-23T09:47:29Z

Howardsmiller:

==Random comments about 2.0 release documentation==
*[[Course completion]] aka [[Course completion tracking]] - a MAJOR new feature not listed or at least does not jump out --[[User:chris collman|chris collman]] 12:15, 26 November 2010 (UTC)
::Realized it was there. I know "completion" is also a feature common with conditional activities. Someone looking for course conditions of entry is not going to think completion has anything to do with it. I put the activity stuff with conditional activities and change the subheading to "Course completion and prerequsites". Sorry if I overstepped my bounds here.--[[User:chris collman|chris collman]] 13:14, 26 November 2010 (UTC)

*[[Activity completion]] - here it is called [[Conditional activities]]. --[[User:chris collman|chris collman]] 12:15, 26 November 2010 (UTC)

==The Lesson activity==
Note 1: when type or paste text formatting does not happen in the page preview.
Note 2: In true / false question, the variable 'Your answer' is equal to feedback message.
Quiz Activity:
Note 1: In question multiple-choice answers entered do not appear in the view of the question. {{Unsigned|José Albuquerque}}

:Hi José, rather than adding comments here, please could you check that any problems/bugs have been reported in the [http://tracker.moodle.org Moodle tracker]. If you're not sure whether something is a bug or not, you can ask about it in the [http://moodle.org/mod/forum/view.php?id=56 Testing and QA forum] in Using Moodle. Thanks in advance for your help! --[[User:Helen Foster|Helen Foster]] 14:50, 17 November 2010 (UTC)

==Rendering Layer Changes==
This points to a page that is marked as obsolete :( --[[User:Howard Miller|Howard Miller]] 09:47, 23 December 2010 (UTC)

Obsolete:Migrating your code to the 2.0 rendering API

2010-12-23T09:44:51Z

Howardsmiller: /* print_header */

<p class="note">
<strong> THIS PAGE IS OUTDATED, DO NOT USE! </strong>
</p>

This page explains how to update your code to take advantage of the new navigation/block/themes/rendering APIs in Moodle 2.0. These changes are explained on [[Development:Navigation 2.0]], [[Development:Navigation 2.0 implementation plan]] and linked pages. You should read that background to understand the changes. This page just explains how you should update your code, not why.

Note that most of the code here has extensive php documentor documentation. Please use that [http://phpdocs.moodle.org/HEAD/index.html API documentation] if you want more details of how to use this new code. If you really want to know how it works see [[Developement:How_Moodle_outputs_HTML]], and I hope the code is readable and well commented.

==General note==

First of all, go to Administration -> Server -> Debugging, and turn debugging up to DEVELOPER level.

Most of the things that have been deprecated or that need to be changed cause debugging output that explains how to update your code.

I went to a lot of effort to implement all that helpful output, please use it!

==Outputting HTML==
See [[Development:Outputting HTML in 2.0]] for a detailed list of functions to migrate.

HTML used to be output through a mixture of direct echo/print statements, and calls to functions like print_header, print_box, ... in lib/weblib.php.

The functions in weblib have been replaced by a new global $OUTPUT. This generates HTML that you need to echo, so
<code php>
print_box(...);
</code>
becomes
<code php>
global $OUTPUT; // If necessary.
$OUTPUT->box(...);
</code>

(Why do we do this, well by default $OUTPUT is a moodle_core_renderer. However, the theme can choose a different class, and so use different output for, say, a box. As an example look in theme/custom_corners/renderers.php.)

===Outputting complex objects===

Some of the old weblib.php functions had a lot of arguments, for example:
<code php>
choose_from_menu($options, 'outcome_'.$n.'['.$userid.']',
$outcome->grades[$submission->userid]->grade, get_string('nooutcome', 'grades'),
'', 0, false, false, 0, 'menuoutcome_'.$n);
</code>
That was quite difficult to work with. (What do those two false parameters mean?). The equivalent new code looks like
<code php>
$menu = new moodle_select_menu;
$menu->options = $options;
$menu->name = 'outcome_'.$n.'['.$userid.']';
$menu->selectedoption = $outcome->grades[$submission->userid]->grade;
$menu->nothinglabel = get_string('nooutcome', 'grades');
$menu->id = 'menuoutcome_'.$n;
echo $OUTPUT->select_menu($menu);
</code>
The new code is more verbose, but much easier to understand ([http://moodle.org/mod/forum/discuss.php?d=126220 discussion]).

If fact if you remember the old print_table method, this approach will be quite familiar. However, note that we now use a real class, rather than stdClass. The main reason for that is that it lets us document the structure ([http://phpdocs.moodle.org/HEAD/moodlecore/moodle_select_menu.html see here for an example). It also makes it easy to set defaults and lets IDEs offer autocompletion.

===print_header===

The old print_header function becomes $OUTPUT->header(). Instead of passing millions of arguments to that function, instead you set propeties on $PAGE. For exampe:

The Moodle 1.9 code
<code php>
$navlinks = array(array('name'=>$strparticipants, 'link'=>$CFG->wwwroot.'/user/index.php?id='.$courseid, 'type'=>'misc'),
array('name'=>$strgroups, 'link'=>'', 'type'=>'misc'));
$navigation = build_navigation($navlinks);
print_header(get_string('publishcourse'), $course->fullname, $navigation,'',$meta, true, ' ', user_login_string($course, $USER));
</code>

Becomes the following Moodle 2.0 code
<code php>
require_login( $course );
$PAGE->set_title(get_string('publishcourse'));
$PAGE->set_heading($course->fullname);
$PAGE->set_focuscontrol('');
$PAGE->set_cacheable(true);
$PAGE->set_button('$nbsp;');
$PAGE->set_headingmenu(user_login_string($course, $USER));
$PAGE->navbar->add($strparticipants, null, null, navigation_node::TYPE_CUSTOM, new moodle_url($CFG->wwwroot.'/user/index.php?id='.$courseid));
$PAGE->navbar->add($strgroups);
echo $OUTPUT->header();
</code>

NOTE: The '''require_login()''' does some magic in the background to set up $PAGE. If you don't have it you may have to do some more work.

The following arguments are no longer supported at all. They were not being used anywhere in core code in a way that could not be handled by a better mechanism.
* meta
* usexml
* bodytags

===Outputting HTML specific to your module===

$OUTPUT lets themes customise the HTML used for standard things like boxes, but what about places where code echoes HTML directly? Well, in addition to moodle_core_renderer, every plugin should also define its own renderer, like moodle_mod_workshop_renderer, and all module-specific HTML output should done in methods of that class. That class should be defined in a files called renderers.php inside your plugin.

When you actually want to do some output, you need to get an instance of your class (or whatever subclass the theme wants to substitute). You do that like this:
<code php>
global $PAGE; // If necessary.
$wsoutput = $PAGE->theme->get_renderer('mod_workshop', $PAGE);
echo $wsoutput->manual_allocation_interface($workshop, $allocationdata);
</code>
The moodle_mod_workshop_renderer object will have access to a moodle_core_renderer available as $this->output. You should use this instead of global $OUTPUT, and you should use it. That is, boxes in the workshop should look like boxes elsewhere, so boxes in the workshop should be output with $this->output->box().

===Don't panic!===

Completely updating your code to use the new output methods everywhere, and writing a renderer class is a big job. The good news is that you don't have to. All the old weblib methods have been moved to deprecatedlib, and now call $OUTPUT, so all your old code will go on working. You can update it at your leisure. (Of course, eventually, the old methods will be removed, so you should update some time.)

==Blocks==

=== Settings forms ===

==== Global ====

config_global.html files must be replaced by a [[Development:Admin_settings|settings.php]] file, just like other plugin types. (There is rudimentary support for config_global.html files still in the code, but you should not rely on it.)

==== Instance ====

config_instance.html files must be replaced by a proper settings form. The form must be a subclass of block_settings_form called block_''myblock''_edit_form defined in the file blocks/''myblock''/edit_form.php.

In addition, the old instance_config_print is no longer used, so any code there needs to be moved into the form class you create.

blocks/html/edit_form.php is a nice simple example to look at. Other blocks mentioned in MDL-19889 provide more complex examples. The [http://tracker.moodle.org/browse/MDL-19889?page=com.atlassian.jira.plugin.system.issuetabpanels%3Acvs-tabpanel changes associated with that bug] show you exactly how to covert a block.

There is currently no backwards-compatible support for old config_instance.html files. It would be hard to do that. It might be possible if people really need it, but no-one has had time to try yet.

=== Other API changes ===

* The method block_base::preferred_width is no longer used the width of blocks is entirely controlled by the theme. If your block is too wide, it will probably get cropped with overflow: hidden. See http://moodle.org/mod/forum/discuss.php?d=122525 for discussion.

* Code in the block that relied on $this->instance->... will probably break. Information about the page the block is appearing on is available from $this->page->.... Specifically:
** $this->instance->pagetype should be changed to $this->page->pagetype
** $this->instance->pageid - there is no longer a concept of page id. Instead, you are probably looking for $this->page->course, $this->page->cm or $this->page->activityrecord. See below for more on $PAGE.

=== Useful new stuff ===

* Every block now has access to the page it appears on, via $this->page. (Therefore, you do not have to use the global $PAGE object in blocks!)

* Every block now has its own context, and you can always access it via $this->context. However when checking permissions you need to decide which of two contexts is more appropriate:
*# The block context ($this->context)
*# The page context the block is appearing on ($this->page->context). For sticky blocks, this may be a more appropriate choice.
For example, when deciding whether the user can edit the block settings, or see the block, you should use the block context. When deciding whether the user can do something relating to the context where the block appears (can the user see participants here) you should probably use the page context.

=== Other things to be aware of ===

Note that the way the blocks are output to HTML has changed. However, there has been no change to the blocks API, so you should not have to make any changes, unless you had overridden formerly 'private' methods.

==Activity modules==

See also the section on [[#Outputting blocks]] below.

===Blocks upgrade===

If you have a custom module that has a pagelib.php file, then you need to ensure it is included in the blocks upgrade. Just look for the bit in lib/db/upgrade.php that says
<code php>
$moduleswithblocks = array('chat', 'data', 'lesson', 'quiz', 'dimdim', 'game', 'wiki', 'oublog');
</code>
and add the name of your module. You must do this before trying to upgrade your site.

If you have done something more complicated than what is in the NEWMODULE template, then you will have to write more custom code.

===in mod/.../view.php===

You need to change how $PAGE is initialised.
* Don't call page_create_instance any more. It is deprecated, and if you do, you should see a debug warning. (You do you development with debugging set to DEBUG_DEVELOPER, right?)
* In fact, you probably only need to replace the line
<code php>
$PAGE = page_create_instance($chat->id);
</code>
with
<code php>
$PAGE->set_url('mod/MYMOD/view.php', array('id' => $cm->id));
</code>
* Take the code that is left in page_generic_activity::print_header in inline it in your view.php file at the point where you used to call $PAGE::print_header. You will need to fix it up to make it work, but normally that involves deleting about half of it and editing the rest a bit. Some helpful notes:
** $this->modulerecord -> $cm
** $this->$course -> $course
** $this->activityname -> ''<nowiki>'MYMOD'</nowiki>''
** Change the complicated mess that computes $title into a simple line of code.
** Other instances of $this -> $PAGE
** See if $meta, $bodytags and so on are acutally used, and if not remove them.
* Delete your 'mod/MYMOD/pagelib.php' file, and any places where it is included.

To help with this conversion, the regex '''page_|\$PAGE|pagelib''' is a good thing to search for.

===in ..._delete_instance in lib.php===

You used to have to worry about deleting blocks when an instance of your module was deleted. You can forget about that now, since all blocks data are deleted automatically when a context is deleted.

That is, code like
<code php>
$pagetypes = page_import_types('mod/chat/');
foreach($pagetypes as $pagetype) {
if(!blocks_delete_all_on_page($pagetype, $chat->id)) {
$result = false;
}
}
</code>
in lib.php can just be deleted.

==$PAGE==

It is no longer necessary to write subclasses of page_base, and in fact, such subclasses are no longer used. Instead there is a single moodle_page class, and an instance of that is automatically created as $PAGE.

Do not set $CFG->pagepath. Instead, call $PAGE->set_pagetype(); For example
<code php>
$CFG->pagepath = 'question/type/' . $question->qtype;
</code>
becomes
<code php>
$PAGE->set_pagetype('question-type-' . $question->qtype);
</code>

===blocks_... methods===

If your page subclass used to try to control blocks you need to change it to get equivalent functionality

; blocks_get_positions
; blocks_default_position
: You no longer control this. These settings now belong to the theme. However, if you want special extra block areas on certain pages, then you can call $PAGE->blocks->add_region('myregion');
; blocks_get_default
: No longer supported. Instead, in your .../db/install.php you should probably do blocks_create_block('blockname', get_context_instance(CONTEXT_SYSTEM), BLOCKS_SHOWINSUBCONTEXTS, 'my-page-type');
; blocks_move_position
: No longer required at all. The way blocks editing now works means that it is unnecessary.

===url_... methods===

Instead of implementing the url_get_parameters and url_get_path() methods, you should instead be setting the $PAGE->set_url(...) method from within your script.

===user_... methods===

; user_is_editing
: is now implemented by the base class and should not be changed.
; user_allowed_editing is also implemented by the base class, you must call $PAGE->set_block_editing_capability and/or $PAGE->set_other_editing_capability to set the right logic. By default, editing can be turned on on a page if if the user has the 'moodle/site:manageblocks' capability in the page context.

===print_header===

the page object no longer has any responsibility for printing the header. Your script should do it directly. This means that if you page class has a print_header method, you should move that code elsewhere.

===Other changes===

* Code that used to rely on the ->courserecord field of pages should be changed to refer to ->course.
* Calls to $PAGE->get_type() should be changed to $page->pagetype.
* page_id_and_class, which was used to initialise and return the pagetype (as $getid) is no longer necessary. Just use $PAGE->pagetype.
* $PAGE->get_format_name is deprecated. use $PAGE->pagetype instead.

==Libraries to include==

lib/blocklib.php and lib/pagelib.php are now always included by config.php. Therefore you should clean up any places in your code where you explicitly require_once them.

==$CFG->pixpath and $CFG->modpixpath==

$CFG->pixpath and $CFG->modpixpath are now deprecated. Old code like "$CFG->pixpath/i/course.gif" should be changed to $OUTPUT->pix_url('i/course') and code like "$CFG->modpixpath/$mod/icon.gif" should be changed to $OUTPUT->pix_url('icon', $mod->modname).

When I started converting Moodle core code, there were 467 matches for the regular expression '''/\$CFG->(mod)?pixpath/''' - that will find all the places in the code you have to update.

I used the following regular expressions (Eclipse regular expression search and replace) to fix a lot of them semi-automatically.

\$CFG->pixpath ?\. ?'/((\w/)?[a-zA-Z0-9_-]+)\.(gif|png)
->
\$OUTPUT->pix_url('$1') . '
(225 matches in HEAD)

\{?\$CFG->pixpath\}?/(\w/[a-zA-Z0-9_-]+)\.(gif|png)
->
" . \$OUTPUT->pix_url('$1') . "
(68 matches in HEAD)

\$CFG->pixpath ?\. ?'/([a-zA-Z0-9_-]+)\.(gif|png)
->
\$OUTPUT->pix_url('$1') . '
(29 matches in HEAD)

\$CFG->modpixpath ?\. ?'/' ?\. ?([^\.]+) ?\. ?'/icon\.gif
->
\$OUTPUT->mod_icon_url('icon', $1) . '
(12 matches in HEAD)

\$CFG->modpixpath/([^/]+)/icon.gif
->
" . \$OUTPUT->mod_icon_url('icon', $1) . "
(13 matches in HEAD)

After you have done the automatic replaces, you need to review the changes (e.g. using cvs diff) because sometimes you end up with code like . "" . that should be cleaned up, and the search and replace cannot add global $OUTPUT; where necessary, nor remove no longer necessary global $CFG; statements.

== Outputting blocks ==

Blocks are now output by the theme, in its layout.php file. Any code you have in your scripts that calls blocks_setup, blocks_preferred_width, blocks_have_content or blocks_print_group should just be deleted. http://git.moodle.org/gw?p=moodle.git;a=commitdiff;h=d4a03c00ea3885ac2b264b7d7a8c6c635d5714d2#patch31 is typical of how to update a script.

== Themes ==

''Please don't forget to take the advice [[#General note|above]] and turn [[Debugging|debugging]] up to DEVELOPER level. That will give you lots of helpful debug output that tells you what you need to update.''

=== header.html and footer.html replaces by layout.php ===

Instead of separate header.html and footer.html files for the top and bottom of the page, there is now a single layout.php template. You need to create a layout.php file for your theme.

To create layout.php, you basically need to merge your header.html and footer.html files with "[MAIN CONTENT GOES HERE]" in the middle. Then update the resulting code to match the kind of things done in ''theme/standard/layout.php''. This is explain in more detail in the next few sections.

=== layout.php should get data from $PAGE ===

In the past, header.html and footer.html had to rely on certain variables that were set up in the print_header and print_footer functions. Instead, you should now get the information you want from properties of $PAGE, or call $OUTPUT methods to output various standard things.

The '''replacements''' for the various old variables are:

<code php>
// Old code in header/footer.html -> // New code in layout.php
[hard-coded doctype] -> <?php echo $OUTPUT->doctype() ?>
<?php echo $direction ?> -> <?php echo $OUTPUT->htmlattributes(); ?>
$title -> $PAGE->title;
$heading -> $PAGE->heading;
$focus -> $PAGE->focuscontrol;
$button -> $PAGE->button;
$pageid -> $PAGE->pagetype;
$pageclass -> $PAGE->bodyclasses;
<?php echo " $bodytags"; ?> -> id="<?php echo $PAGE->pagetype ?>" class="<?php echo $PAGE->bodyclasses ?>"
if ($home) {... -> if ($PAGE->generaltype == 'home') {...
$homelink -> $OUTPUT->home_link();
$loggedinas -> $OUTPUT->login_info();
$course -> $PAGE->course;
</code>

Some standard bits that used to be present need to be '''deleted''':

<code php>
// Delete these bits that used to be in header/footer.html
<?php echo $meta ?>
<meta name="keywords" content="moodle, <?php echo $title ?> " />
<?php include("$CFG->javascript"); ?>
if (!empty($performanceinfo)) {
echo $performanceinfo;
}
</code>

And certain new bits need to be '''added''':

<code php>
// Add these bits in the appropriate places in layout.php
<?php echo $OUTPUT->standard_head_html() ?>
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<?php echo $OUTPUT->standard_footer_html() ?>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</code>

=== Themes must print the blocks ===

You must also add code to your layout.php to output any blocks.

Typically the code will look something like:
<code php>
// Add code like this in the appropriate places in layout.php
<?php if ($PAGE->blocks->region_has_content('side-pre')) { ?>
<div id="region-side-pre" class="block-region">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
<?php } ?>
</code>

As I said above, the quickest way to get the hang of all the things you need to do in layout.php is by example. Look at [http://cvs.moodle.org/moodle/theme/standard/layout.php?view=markup theme/standard/layout.php], or other examples in the standard Moodle themes.

=== You can have different layout.php files for different page. ===

Pages in Moodle are now classified into one of a few general types, like 'normal', 'home', 'form', 'popup', ...

If you wish, you can specify a different template for each one. Also, each type of template can have any number of regions for blocks. This is controlled by the $THEME->layouts setting in your theme's config.php. Here is an example.

<code php>
// Code in theme config.php
$THEME->layouts = array(
// Most pages. Put this first, so if we encounter an unknown page type, this is used.
'normal' => array(
'layout' => 'standard:layout.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
),
// The site home page.
'home' => array(
'layout' => 'layout-home.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
),
// Settings form pages, like course of module settings.
'form' => array(
'layout' => 'standard:layout.php',
'regions' => array(),
),
// Pages that appear in pop-up windows.
'popup' => array(
'layout' => 'standard:layout-popup.php',
'regions' => array(),
),
// Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
'maintenance' => array(
'layout' => 'standard:layout-popup.php',
'regions' => array(),
),
);
</code>

What you see there is that for each type of page, which layout file to use, and where blocks may appear.

There are three ways you can specify a layout file. It may be in this theme (for example layout-home.php) or it may come from the parent theme (for example you could say parent:layout.php) or from the standard theme (for example standard:layout-popup.php).

Some templates have 'regions' for blocks and others don't. You can even use a template that has block regions (like standard:layout.php) but then say you don't want any blocks there, as for 'form' pages in the example above. Note that the default names for regions are now side-pre and side-post. That makes more sends than left and right in right-to-left languages.

If there are block regions, then you must specify one of them as the default. That is where the 'Add new blocks' pretend block appears, and where new blocks are added.

Also, suppose someone adds some blocks while using another theme that uses one set of names for its block regions, and then switches to your theme that uses different names. We don't want some of the blocks to just disappear, so any blocks from unrecognised regions are shown at the end of the default region.

=== styles.php ===

The standard form for the styles.php file has changed (become simpler). Please copy the latest theme/standard/styles.php into your theme.

=== No longer supported options in config.php ===

Note that there is now documentation about all the things you can set in config.php at http://phpdocs.moodle.org/HEAD/moodlecore/theme_config.html.

All the separate $THEME->modsheets = true; $THEME->blocksheets = true; ... settings have been replaced by a single
<code php>
$THEME->pluginsheets = array('mod', 'block', 'format', 'gradereport');
</code>
setting, and all plugin types are now supported.

$THEME->customcorners = true; should be changed to $this->rendererfactory = 'custom_corners_renderer_factory';

$THEME->cssconstants = true; is no longer supported in config.php files. Use $THEME->customcssoutputfunction = 'output_css_replacing_constants';

$THEME->CSSEdit = true; is no longer supported in config.php files. Use $THEME->customcssoutputfunction = 'output_css_for_css_edit';

== JavaScript ==

The way in which JavaScript is included for a page has now changed and methods have been provided for $PAGE to require JavaScript within a page.
As part of this change several JavaScript libraries that were been included on every page are not any more, and if you have code that was using them you need to modify it to manually include these JavaScript files.

=== Replacement for require_js() ===

In the past we have had a function called require_js(), which made it very easy to make sure that you JavaScript files you wanted got linked to somewhere, and that each file was linked to no more than once.

That was very nice, but only went so far. For example, there was no equivalent require_css(), and some of the [[Development:YUI|YUI]] libraries need their own CSS files to work properly. Also, you could not control when the JS was linked to and [http://moodle.org/mod/forum/discuss.php?d=106312 as discussed here], it is best to link to most of the JavaScript from the end of the HTML, not from <head> because that gives better page-load performance.

Of course some things cannot wait that long and do need to be included in HEAD or in some cases within the body of the page, in other cases if your script is at the end of the page and you need to call an init function then that initialise function had also better be at the end of the page.

As such the requirements have become more complicated and in order to handle them a new '''[http://phpdocs.moodle.org/HEAD/moodlecore/page_requirements_manager.html page_requirements_manager]''' was created to replace require_js().

The following are examples of how to use the new page requirements manager.

<code php>
$PAGE->requires->css('mod/mymod/styles.css');
$PAGE->requires->yui_lib('autocomplete'); // YUI requirements are known about
// and automatically included, without you needing to call yui_lib for each one
$PAGE->requires->js('mod/mymod/script.js');
$PAGE->requires->js('mod/mymod/small_but_urgent.js')->in_head();
echo $PAGE->requires->js('mod/mymod/small_but_urgent.js')->asap();
$PAGE->requires->js_function_call('init_mymod', array($data))->on_dom_ready();
$PAGE->requires->data_for_js('mydata', Array('name1'=>$value1, 'name2'=>$value2));
</code>

=== Unobtrusive Flash Objects - ufo.js ===

The UFO JS object used to display inline media is no longer included on every page. If you have any code that is relying on the UFO library you will need to update it in order for it to work.

In order to use the UFO you will need to include the following line of code.

<code php>
global $PAGE; // You will only need this if you are within a function
$PAGE->requires->js('lib/ufo.js'); // Only use ->asap() or ->in_head() if you really need to
</code>

A good idea at the same time might be to convert your code to use the new $PAGE methods to the full extent which can be done in the following fashion.

''From''
<code php>
echo '<script type="text/javascript">';
echo '//<![CDATA[';
echo ' var FO = { movie:"'.$CFG->wwwroot.'/filter/mediaplugin/mp3player.swf?src='.$url.'",';
echo ' width:"90", height:"15", majorversion:"6", build:"40", flashvars:"'.$c.'", quality: "high" };';
echo ' UFO.create(FO, "'.$id.'");';
echo '//]]>';
echo '</script>';
</code>
''To''
<code php>
$ufoargs = Array();
$ufoargs['movie'] = $CFG->wwwroot.'/filter/mediaplugin/mp3player.swf?src='.$url;
$ufoargs['width'] = 90;
$ufoargs['height'] = 15;
$ufoargs['majorversion'] = 6;
$ufoargs['build'] = 40;
$ufoargs['quality'] = 'high';
$PAGE->requires->js('lib/ufo.js');
$PAGE->requires->data_for_js('FO', $ufoargs);
$PAGE->requires->js_function_call('create_UFO_object', Array('myelementid'));
</code>

=== DOM events ===
In the past we have used DOM events inline within HTML elements. Now that we are avoiding inline JavaScript, these methods are no longer suitable. The new rendering API in lib/outputlib.php abstracts all event handlers into a simple approach.
# JS functions you want to call when an event is triggered must be written in a JS-only text file (no PHP)
# These functions MUST have 2 params only: event and args. Args is a JS object with named variables which you can use in your function. The event object is used to determine the target of the event (the element to which the event handler is attached), and the type of event that was triggered.
# To output a HTML element that has an event handler, you must use a subclass of moodle_html_component. These objects have an add_action() method which takes a component_action object or 2-3 params as described in the phpdocs.
# In the rendering methods of the $OUTPUT object, the render::prepare_event_handlers($component) is called and the appropriate YUI Javascript is added to the page, creating an event listener on the given object.
An example follows:
<code php>
$image = new html_image();
$image->src = $src;
$image->add_action('click', 'show_large_version', array('title' => 'Large version', 'description' => 'a lovely image'));
echo $OUTPUT->image($image);
</code>
This examples will output an image which, when clicked, will trigger the call to the show_large_version() JS function, passing the event object and a JS object with two named variables: title and description. That function may look like this:
<code javascript>
function show_large_version(e, args) {
var title = args.title;
var description = args.description;
popup(this.src, title, description); // An imaginary function
}
</code>
Note, in the JS function above, the use of "this", which is the element that triggered the event. It can be obtained through the event object too.

==Information for admins==

''This probably needs to be moved into the release notes when it is done.''

===Some hidden blocks my become un-hidden during the upgrade===

In Moodle 1.9, it was, in theory, possible to add a sticky block to a type of page, and then make that stickyblock hidden. The way blocks are hidden in Moodle 2.0 is slightly different, so if in your Moodle 1.9 site you had hidden sticky blocks, they will become visible during the upgrade to Moodle 2.0.

Also, in a few situations, other non-sticky blocks that were hidden may becomes visible. (This will only happen if the block appeared on more than one page. For example, if you have a hidden block on a course page, and also have enabled showing course blocks on resource pages, then the block will be visible on the resource page until you hide it again.) If there are specific identifiable instances of this problem, it may be possible to improve the upgrade code while Moodle is in beta testing.

==See also==

* [[Developement:How_Moodle_outputs_HTML]]
* [[Development:Navigation 2.0]]
* [[Development:Navigation 2.0 implementation plan]]
* [[Development:Outputting HTML in 2.0]]

{{CategoryDeveloper}}

Debugging

2010-12-22T09:25:58Z

Howardsmiller: /* In config.php */

Location: ''Administration > Server > Debugging''

Debugging messages are intended to help diagnose problems and/or help Moodle developers. If you have a problem with your Moodle site and ask for help in a Moodle.org forum, a developer may ask you to turn debug messages on, in order to locate the cause of the problem. By default Moodle does not show any error messages at all. If you are having problems (e.g. blank screens or incomplete screens) turning on debugging is usually the first thing to try.

==How to turn on debugging==

Go into the admin screens, and look under Administration > Server > Debugging (In Moodle 2.0 it is Site administration ▶ Development ▶ Debugging). Set the...

* '''Debug messages''' to '''ALL''', and
* '''Display debug messages''' to '''Yes'''.

(You '''must''' do both). There is rarely any advantage in going to Developer level, unless you are a developer, in which case it is strongly recommended.

Once you have got the error message, and copied and pasted it somewhere, you are recommended to turn debugging back off again.

==Debug messages==

{{Moodle 1.7}}From Moodle 1.7 onwards, further options are provided for controlling how to handle PHP error messages. The administrator can select the types of error messages to be displayed or logged.

The options for debugging include:
* NONE: Do not show any errors or warnings
* MINIMAL: Show only fatal errors
* NORMAL: Show errors, warnings and notices
* ALL: Show all reasonable PHP debug messages. When you want to find the cause of a problem with your site, this is probably best the setting to use.
* DEVELOPER: extra Moodle debug messages for developers - If you turn this on, then PHP's error_reporting will be increased so that more warnings are printed. This is almost essential for developers, but not very helpful for anyone else.

==Display debug messages==

There is an option to choose whether to display error messages or simply record them in the server logs.

==Debug email sending==

Determines whether or not to enable verbose debug information during sending of email messages to SMTP server.

==Performance info==

The Performance info option determines whether performance info will be included in the footer of the standard theme (and some other themes). Performance info includes the time for the page to load, the amount of memory used to generate the page, cpu usage, load, and the record cache hit/miss ration.

If you add
<code php>
define('MDL_PERF', true);
define('MDL_PERFDB', true);
define('MDL_PERFTOLOG', true);
define('MDL_PERFTOFOOT', true);
</code>
to your config.php file, then it will also count database queries. (This has to be in config.php, because Moodle starts doing DB queries before it loads the config information in the database!

==What to do if you cannot get to the admin screens==

If the error is stopping you even getting to the admin screens to turn on debugging, then you can set the debugging setting manually.

===Try typing the URL directly===

The debug settings are at the URL <code><nowiki>http://.../admin/settings.php?section=debugging</nowiki></code> on your server. Sometimes that URL will work, even though the pages you need to go to to get there (for example the site front page) do not. So it is worth trying to enter that URL directly.

===In config.php===

In moodle/config.php you can add the lines:

<code php>
$CFG->debug = 2047;
$CFG->debugdisplay = 1;
</code>

Or even more debugging messages:

<code php>
$CFG->debug = 6143;
$CFG->debugdisplay = 1;
</code>

{{Moodle 2.0}}For Moodle 2.0 the possible settings are as follows:

<code php>
// Force a debugging mode regardless the settings in the site administration
// @error_reporting(1023); // NOT FOR PRODUCTION SERVERS!
@ini_set('display_errors', '1'); // NOT FOR PRODUCTION SERVERS!
$CFG->debug = 38911; // DEBUG_DEVELOPER // NOT FOR PRODUCTION SERVERS!
$CFG->debugdisplay = true; // NOT FOR PRODUCTION SERVERS!

// You can specify a comma separated list of user ids that that always see
// debug messages, this overrides the debug flag in $CFG->debug and $CFG->debugdisplay
// for these users only.
$CFG->debugusers = '2';
</code>

Remember to remove those lines again when you have finished diagnosing your problem.

===In the database===

Using a tool like phpMyAdmin, execute the following SQL commands:

<code sql>
UPDATE mdl_config SET value = 2047 WHERE name = 'debug';
UPDATE mdl_config SET value = 1 WHERE name = 'debugdisplay';
</code>

To turn it back off, use the admin screens, or the commands:

<code sql>
UPDATE mdl_config SET value = 0 WHERE name = 'debug';
UPDATE mdl_config SET value = 0 WHERE name = 'debugdisplay';
</code>

(If you use a different database prefix, you will need to adjust those commands accordingly.)

==See also==

* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=91031 Debugging Turned on to Developer Mode on 1.8.2] forum discussion including instructions on how to turn debugging off

[[Category:Administrator]]

[[fr:Débogage]]

Debugging

2010-12-22T09:24:49Z

Howardsmiller: /* In config.php */

Location: ''Administration > Server > Debugging''

Debugging messages are intended to help diagnose problems and/or help Moodle developers. If you have a problem with your Moodle site and ask for help in a Moodle.org forum, a developer may ask you to turn debug messages on, in order to locate the cause of the problem. By default Moodle does not show any error messages at all. If you are having problems (e.g. blank screens or incomplete screens) turning on debugging is usually the first thing to try.

==How to turn on debugging==

Go into the admin screens, and look under Administration > Server > Debugging (In Moodle 2.0 it is Site administration ▶ Development ▶ Debugging). Set the...

* '''Debug messages''' to '''ALL''', and
* '''Display debug messages''' to '''Yes'''.

(You '''must''' do both). There is rarely any advantage in going to Developer level, unless you are a developer, in which case it is strongly recommended.

Once you have got the error message, and copied and pasted it somewhere, you are recommended to turn debugging back off again.

==Debug messages==

{{Moodle 1.7}}From Moodle 1.7 onwards, further options are provided for controlling how to handle PHP error messages. The administrator can select the types of error messages to be displayed or logged.

The options for debugging include:
* NONE: Do not show any errors or warnings
* MINIMAL: Show only fatal errors
* NORMAL: Show errors, warnings and notices
* ALL: Show all reasonable PHP debug messages. When you want to find the cause of a problem with your site, this is probably best the setting to use.
* DEVELOPER: extra Moodle debug messages for developers - If you turn this on, then PHP's error_reporting will be increased so that more warnings are printed. This is almost essential for developers, but not very helpful for anyone else.

==Display debug messages==

There is an option to choose whether to display error messages or simply record them in the server logs.

==Debug email sending==

Determines whether or not to enable verbose debug information during sending of email messages to SMTP server.

==Performance info==

The Performance info option determines whether performance info will be included in the footer of the standard theme (and some other themes). Performance info includes the time for the page to load, the amount of memory used to generate the page, cpu usage, load, and the record cache hit/miss ration.

If you add
<code php>
define('MDL_PERF', true);
define('MDL_PERFDB', true);
define('MDL_PERFTOLOG', true);
define('MDL_PERFTOFOOT', true);
</code>
to your config.php file, then it will also count database queries. (This has to be in config.php, because Moodle starts doing DB queries before it loads the config information in the database!

==What to do if you cannot get to the admin screens==

If the error is stopping you even getting to the admin screens to turn on debugging, then you can set the debugging setting manually.

===Try typing the URL directly===

The debug settings are at the URL <code><nowiki>http://.../admin/settings.php?section=debugging</nowiki></code> on your server. Sometimes that URL will work, even though the pages you need to go to to get there (for example the site front page) do not. So it is worth trying to enter that URL directly.

===In config.php===

In moodle/config.php you can add the lines:

<code php>
$CFG->debug = 2047;
$CFG->debugdisplay = 1;
</code>

Or even more debugging messages:

<code php>
$CFG->debug = 6143;
$CFG->debugdisplay = 1;
</code>

For Moodle 2.0 the possible settings are as follows:

<code php>
// Force a debugging mode regardless the settings in the site administration
// @error_reporting(1023); // NOT FOR PRODUCTION SERVERS!
@ini_set('display_errors', '1'); // NOT FOR PRODUCTION SERVERS!
$CFG->debug = 38911; // DEBUG_DEVELOPER // NOT FOR PRODUCTION SERVERS!
$CFG->debugdisplay = true; // NOT FOR PRODUCTION SERVERS!

// You can specify a comma separated list of user ids that that always see
// debug messages, this overrides the debug flag in $CFG->debug and $CFG->debugdisplay
// for these users only.
$CFG->debugusers = '2';
</code>

Remember to remove those lines again when you have finished diagnosing your problem.

===In the database===

Using a tool like phpMyAdmin, execute the following SQL commands:

<code sql>
UPDATE mdl_config SET value = 2047 WHERE name = 'debug';
UPDATE mdl_config SET value = 1 WHERE name = 'debugdisplay';
</code>

To turn it back off, use the admin screens, or the commands:

<code sql>
UPDATE mdl_config SET value = 0 WHERE name = 'debug';
UPDATE mdl_config SET value = 0 WHERE name = 'debugdisplay';
</code>

(If you use a different database prefix, you will need to adjust those commands accordingly.)

==See also==

* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=91031 Debugging Turned on to Developer Mode on 1.8.2] forum discussion including instructions on how to turn debugging off

[[Category:Administrator]]

[[fr:Débogage]]

Debugging

2010-12-22T09:24:23Z

Howardsmiller: /* In config.php */

Location: ''Administration > Server > Debugging''

Debugging messages are intended to help diagnose problems and/or help Moodle developers. If you have a problem with your Moodle site and ask for help in a Moodle.org forum, a developer may ask you to turn debug messages on, in order to locate the cause of the problem. By default Moodle does not show any error messages at all. If you are having problems (e.g. blank screens or incomplete screens) turning on debugging is usually the first thing to try.

==How to turn on debugging==

Go into the admin screens, and look under Administration > Server > Debugging (In Moodle 2.0 it is Site administration ▶ Development ▶ Debugging). Set the...

* '''Debug messages''' to '''ALL''', and
* '''Display debug messages''' to '''Yes'''.

(You '''must''' do both). There is rarely any advantage in going to Developer level, unless you are a developer, in which case it is strongly recommended.

Once you have got the error message, and copied and pasted it somewhere, you are recommended to turn debugging back off again.

==Debug messages==

{{Moodle 1.7}}From Moodle 1.7 onwards, further options are provided for controlling how to handle PHP error messages. The administrator can select the types of error messages to be displayed or logged.

The options for debugging include:
* NONE: Do not show any errors or warnings
* MINIMAL: Show only fatal errors
* NORMAL: Show errors, warnings and notices
* ALL: Show all reasonable PHP debug messages. When you want to find the cause of a problem with your site, this is probably best the setting to use.
* DEVELOPER: extra Moodle debug messages for developers - If you turn this on, then PHP's error_reporting will be increased so that more warnings are printed. This is almost essential for developers, but not very helpful for anyone else.

==Display debug messages==

There is an option to choose whether to display error messages or simply record them in the server logs.

==Debug email sending==

Determines whether or not to enable verbose debug information during sending of email messages to SMTP server.

==Performance info==

The Performance info option determines whether performance info will be included in the footer of the standard theme (and some other themes). Performance info includes the time for the page to load, the amount of memory used to generate the page, cpu usage, load, and the record cache hit/miss ration.

If you add
<code php>
define('MDL_PERF', true);
define('MDL_PERFDB', true);
define('MDL_PERFTOLOG', true);
define('MDL_PERFTOFOOT', true);
</code>
to your config.php file, then it will also count database queries. (This has to be in config.php, because Moodle starts doing DB queries before it loads the config information in the database!

==What to do if you cannot get to the admin screens==

If the error is stopping you even getting to the admin screens to turn on debugging, then you can set the debugging setting manually.

===Try typing the URL directly===

The debug settings are at the URL <code><nowiki>http://.../admin/settings.php?section=debugging</nowiki></code> on your server. Sometimes that URL will work, even though the pages you need to go to to get there (for example the site front page) do not. So it is worth trying to enter that URL directly.

===In config.php===

In moodle/config.php you can add the lines:

<code php>
$CFG->debug = 2047;
$CFG->debugdisplay = 1;
</code>

Or even more debugging messages:

<code php>
$CFG->debug = 6143;
$CFG->debugdisplay = 1;
</code>

For Moodle 2.0 the possible settings are as follows:

<code php?
// Force a debugging mode regardless the settings in the site administration
// @error_reporting(1023); // NOT FOR PRODUCTION SERVERS!
@ini_set('display_errors', '1'); // NOT FOR PRODUCTION SERVERS!
$CFG->debug = 38911; // DEBUG_DEVELOPER // NOT FOR PRODUCTION SERVERS!
$CFG->debugdisplay = true; // NOT FOR PRODUCTION SERVERS!

// You can specify a comma separated list of user ids that that always see
// debug messages, this overrides the debug flag in $CFG->debug and $CFG->debugdisplay
// for these users only.
$CFG->debugusers = '2';
</code>

Remember to remove those lines again when you have finished diagnosing your problem.

===In the database===

Using a tool like phpMyAdmin, execute the following SQL commands:

<code sql>
UPDATE mdl_config SET value = 2047 WHERE name = 'debug';
UPDATE mdl_config SET value = 1 WHERE name = 'debugdisplay';
</code>

To turn it back off, use the admin screens, or the commands:

<code sql>
UPDATE mdl_config SET value = 0 WHERE name = 'debug';
UPDATE mdl_config SET value = 0 WHERE name = 'debugdisplay';
</code>

(If you use a different database prefix, you will need to adjust those commands accordingly.)

==See also==

* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=91031 Debugging Turned on to Developer Mode on 1.8.2] forum discussion including instructions on how to turn debugging off

[[Category:Administrator]]

[[fr:Débogage]]