MoodleDocs - User contributions [en]

User:Sam Hemelryk

2011-09-23T02:47:09Z

Samhemelryk: Replaced content with "Hi, I maintain my profile on the dev wiki. You can find it here: https://docs.moodle.org/dev/User:Sam_Hemelryk"

Hi, I maintain my profile on the dev wiki.
You can find it here:

https://docs.moodle.org/dev/User:Sam_Hemelryk

User:Sam Hemelryk/My Moodle Git workflow

2011-09-23T02:30:50Z

Samhemelryk: Replaced content with "Hi, this doc has previously existed in a couple of locations and has now been consolidated to just one location. You can now find it here: https://docs.moodle.org/dev/User:Sa..."

Hi, this doc has previously existed in a couple of locations and has now been consolidated to just one location.
You can now find it here:

https://docs.moodle.org/dev/User:Sam_Hemelryk/My_Moodle_Git_workflow

PLEASE DO NOT EDIT THIS PAGE, feel free to edit the linked page above.

Cheers
Sam

Development:Themes 2.0 adding courses and categories to the custom menu

2011-05-06T03:17:56Z

Samhemelryk: /* A word of warning */

Hello this is going to be a very brief tutorial on how to add a courses and categories tree to the custom menu.<br />
The reason for writing this tutorial is simply that this seems to be a request that is being made over and over again.

==Before we get started==
Please please please make sure you are familiar with the other Themes 2.0 tutorials before attempting this tutorial.

In particular I would recommend being familiar with the following documents and tutorials as I'm going to move through this tutorial at a fast pace.

* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]
* [[Development:Themes 2.0 extending the custom menu]]

Providing you are familiar with the above you should manage just fine with this tutorial and if you ever get stuck don't forget to ask in the theme's forums, there is always someone around who can help.

===Two words of warning===
'''First''' Just a quick warning here, this tutorial adds all categories and courses to the navigation, on a site with a large number of categories and/or courses this will be a performance hit. I would strongly suggest that if you are looking to implement something such as this on a large site that you talk to your system admin and/or resident developer about setting up a shared cache and caching the result of the get_course_category_tree method... it is a technical task but doing so will improve the performance of this extension on a large site.

'''Second''' If you have categories nested 2 or more deep then there is a chance that you will run into display problems with the custom menu on some themes... not too much you can do about it but if you encounter it with a core theme and you fix it perhaps you would be kind enough to create an issue in our bug tracker and share the fix. That'd being said this is only a hunch I have all of the theme's may be fine :)

==Laying the ground work==
Alright I don't want this tutorial to drag out so get ready. For this tutorial I am just going to extend the standard theme, I'm going to make absolutely no changes to the design and layout of the theme or the custom menu I am ONLY going to add a list of courses and categories to it.

So to begin with within your Moodle themes directory create a new directory coursecategorymenu in which I want you to create three files, the first config.php which is obviously required, the second renderers.php as we are going to achieve this by overriding a renderer, and the third the English language file for this theme.

You should end up with:

* moodle/theme/coursecategorymenu
* moodle/theme/coursecategorymenu/config.php
* moodle/theme/coursecategorymenu/renderers.php
* moodle/theme/coursecategorymenu/lang/en/theme_coursecategorymenu.php

==config.php==
Obviously because all I want to base this theme off the standard theme and only override a renderer the config.php file is going to be VERY basic, so much so that I'm not going to go into details about it, as you've read the recommended tutorials you will already be completely familiar with everything it is doing.

<code php>
<?php

$THEME->name = 'coursecategorymenu';
$THEME->parents = array('standard', 'base');
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>

==renderers.php==
This is of course where the magic is going to happen.

In my case I want to add a branch to the end of the custom menu titled ''Courses'' and then I want to add the category and course structure to that branch.

So like the [[Development:Themes 2.0 extending the custom menu|extending the custom menu]] tutorial I will be overriding the core renderer and I will also be overriding the render_custom_menu_method.

So the code for this:
<code php>
class theme_coursecategorymenu_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
// Our code will go here shortly
}

}
</code>

You'll notice that is identical to the starting code for the extending custom menu tutorial.

The difference comes in the code that we are going to populate it with:

<code php>
require_once($CFG->dirroot.'/course/lib.php');

$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);

$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}

return parent::render_custom_menu($menu);
</code>

So lets work through this code line by line:

<code php>
require_once($CFG->dirroot.'/course/lib.php');
</code>

This we need to do because we are going to use part of the course API, in particular a function called ''get_course_category_tree()'' that we'll look at shortly.
The function we want to use exists within the course lib file and in order to be sure its always available we need to include this file.

<code php>
$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);
</code>

This line adds the ''Courses'' branch to the custom menu into which we will add the category and course structure.

<code php>
$categorytree = get_course_category_tree();
</code>

This line is the main one to note, here we are calling a Moodle function that will return us a category and course tree, because all courses need to be within a category the initial return is an array of categories, each category in the array will have the properties of the category as well as two additional properties, the first property '''categories''' is an array containing all of this categories sub categories, and the second property '''courses''' is also an array containing all of the courses within this category.

<code php>
$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}
</code>

Now these lines of code deal with the initial array of categories returned by the ''get_course_category_tree'' function.

In this case we iterate of the initial categories and for each one we call a method of the renderer '''add_category_to_custommenu''' now those of you who are clued in will realise that this method doesn't exist yet... and you are correct - we need to write this method which is what we will look at next.<br />
As a heads up the reason that we need to write another method is because we need a method that we can call recursivily as there are potentially infinite category branches all contains sub categories and courses.

<code php>
return parent::render_custom_menu($menu);
</code>

The final line of code simply calls the original render_custom_menu method now that we have extended the custom menu as we want.

Now that we have looked at the render_custom_menu lets write the function we just talked about '''add_category_to_custommenu'''.<br />
This function as discussed above is special in that we intend to call it recursively, that means we want to call it once for EVERY category that exists in the tree. We will need to give it the categories parent menu item as well as the category object we want added.

Lets look at the code for this method:

<code php>
protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
}
</code>

Ok so that doesn't look too bad, as you've already read the extending custom menu tutorial you will be able to spot some of the things it is doing, none the less lets walk through the code.

<code php>
protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
.....
}
</code>

First up the function definition, this function is going to be private because only we need it and it is going to take two arguments, the first $parent has to be a custom_menu_item, the second $category has to be the category object.

The objective of this method is to add a category node to the custom menu, in regards to our arguments we want to add $category as a child of $parent.

<code php>
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
</code>

This line looks very familiar, here we are adding a node for the category to the $parent, we are also collecting the newly added node as $branch.

<code php>
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
</code>

Now this code is responsible for add the sub categories of this category to the menu as well, first we need to check that the categories property isn't empty (if it is there is nothing to add).
Assuming there are sub categories we need go through each of them and call this method on them so that they get added to the custom menu as well.<br />
This is called recursion.

<code php>
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
</code>
This code is very similar to the above code except that we are looking at the courses within this category.<br />
Also note that this bit of code doesn't call add_category_to_custommenu recursivily, it doesn't need to as courses are the last bit we want to display on the menu within the category.

And that is it, time to tidy up and we're done.

==Finishing up==
All of the code is written now there is only last thing to do in order to tidy up however and that is to add the ''courses'' string that we used earlier... did you spot it?

This is of course very easy, open up '''moodle/theme/coursecategorymenu/lang/en/theme_coursecategorymenu.php''' and add the following:

<code php>
<?php

$string['courses'] = 'Courses';
</code>

And we're done. If you now browse to your site and change to the new theme you should see the Courses branch at the end of your custom menu that contains all of the categories, sub categories and courses for your site.

==Full source==
===config.php===
<code php>
<?php

$THEME->name = 'coursecategorymenu';
$THEME->parents = array('standard', 'base');
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>
===renderers.php===
<code php>
<?php

class theme_coursecategorymenu_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
global $CFG;

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

$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);

$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}

return parent::render_custom_menu($menu);
}

protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
}

}
</code>
===lang/en/theme_coursecategorymenu.php===
<code php>
<?php

$string['courses'] = 'Courses';
</code>

==See also==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]
* [[Development:Themes 2.0 extending the custom menu]]
* [http://developer.yahoo.com/yui/3/node-menunav/ YUI 3 Menunav component the custom menu uses]

Development:Themes 2.0 adding courses and categories to the custom menu

2011-05-06T03:11:50Z

Samhemelryk: /* Before we get started */

Hello this is going to be a very brief tutorial on how to add a courses and categories tree to the custom menu.<br />
The reason for writing this tutorial is simply that this seems to be a request that is being made over and over again.

==Before we get started==
Please please please make sure you are familiar with the other Themes 2.0 tutorials before attempting this tutorial.

In particular I would recommend being familiar with the following documents and tutorials as I'm going to move through this tutorial at a fast pace.

* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]
* [[Development:Themes 2.0 extending the custom menu]]

Providing you are familiar with the above you should manage just fine with this tutorial and if you ever get stuck don't forget to ask in the theme's forums, there is always someone around who can help.

===A word of warning===
Just a quick warning here, this tutorial adds all categories and courses to the navigation, on a site with a large number of categories and/or courses this will be a performance hit. I would strongly suggest that if you are looking to implement something such as this on a large site that you talk to your system admin and/or resident developer about setting up a shared cache and caching the result of the get_course_category_tree method... it is a technical task but doing so will improve the performance of this extension on a large site.

==Laying the ground work==
Alright I don't want this tutorial to drag out so get ready. For this tutorial I am just going to extend the standard theme, I'm going to make absolutely no changes to the design and layout of the theme or the custom menu I am ONLY going to add a list of courses and categories to it.

So to begin with within your Moodle themes directory create a new directory coursecategorymenu in which I want you to create three files, the first config.php which is obviously required, the second renderers.php as we are going to achieve this by overriding a renderer, and the third the English language file for this theme.

You should end up with:

* moodle/theme/coursecategorymenu
* moodle/theme/coursecategorymenu/config.php
* moodle/theme/coursecategorymenu/renderers.php
* moodle/theme/coursecategorymenu/lang/en/theme_coursecategorymenu.php

==config.php==
Obviously because all I want to base this theme off the standard theme and only override a renderer the config.php file is going to be VERY basic, so much so that I'm not going to go into details about it, as you've read the recommended tutorials you will already be completely familiar with everything it is doing.

<code php>
<?php

$THEME->name = 'coursecategorymenu';
$THEME->parents = array('standard', 'base');
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>

==renderers.php==
This is of course where the magic is going to happen.

In my case I want to add a branch to the end of the custom menu titled ''Courses'' and then I want to add the category and course structure to that branch.

So like the [[Development:Themes 2.0 extending the custom menu|extending the custom menu]] tutorial I will be overriding the core renderer and I will also be overriding the render_custom_menu_method.

So the code for this:
<code php>
class theme_coursecategorymenu_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
// Our code will go here shortly
}

}
</code>

You'll notice that is identical to the starting code for the extending custom menu tutorial.

The difference comes in the code that we are going to populate it with:

<code php>
require_once($CFG->dirroot.'/course/lib.php');

$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);

$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}

return parent::render_custom_menu($menu);
</code>

So lets work through this code line by line:

<code php>
require_once($CFG->dirroot.'/course/lib.php');
</code>

This we need to do because we are going to use part of the course API, in particular a function called ''get_course_category_tree()'' that we'll look at shortly.
The function we want to use exists within the course lib file and in order to be sure its always available we need to include this file.

<code php>
$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);
</code>

This line adds the ''Courses'' branch to the custom menu into which we will add the category and course structure.

<code php>
$categorytree = get_course_category_tree();
</code>

This line is the main one to note, here we are calling a Moodle function that will return us a category and course tree, because all courses need to be within a category the initial return is an array of categories, each category in the array will have the properties of the category as well as two additional properties, the first property '''categories''' is an array containing all of this categories sub categories, and the second property '''courses''' is also an array containing all of the courses within this category.

<code php>
$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}
</code>

Now these lines of code deal with the initial array of categories returned by the ''get_course_category_tree'' function.

In this case we iterate of the initial categories and for each one we call a method of the renderer '''add_category_to_custommenu''' now those of you who are clued in will realise that this method doesn't exist yet... and you are correct - we need to write this method which is what we will look at next.<br />
As a heads up the reason that we need to write another method is because we need a method that we can call recursivily as there are potentially infinite category branches all contains sub categories and courses.

<code php>
return parent::render_custom_menu($menu);
</code>

The final line of code simply calls the original render_custom_menu method now that we have extended the custom menu as we want.

Now that we have looked at the render_custom_menu lets write the function we just talked about '''add_category_to_custommenu'''.<br />
This function as discussed above is special in that we intend to call it recursively, that means we want to call it once for EVERY category that exists in the tree. We will need to give it the categories parent menu item as well as the category object we want added.

Lets look at the code for this method:

<code php>
protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
}
</code>

Ok so that doesn't look too bad, as you've already read the extending custom menu tutorial you will be able to spot some of the things it is doing, none the less lets walk through the code.

<code php>
protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
.....
}
</code>

First up the function definition, this function is going to be private because only we need it and it is going to take two arguments, the first $parent has to be a custom_menu_item, the second $category has to be the category object.

The objective of this method is to add a category node to the custom menu, in regards to our arguments we want to add $category as a child of $parent.

<code php>
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
</code>

This line looks very familiar, here we are adding a node for the category to the $parent, we are also collecting the newly added node as $branch.

<code php>
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
</code>

Now this code is responsible for add the sub categories of this category to the menu as well, first we need to check that the categories property isn't empty (if it is there is nothing to add).
Assuming there are sub categories we need go through each of them and call this method on them so that they get added to the custom menu as well.<br />
This is called recursion.

<code php>
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
</code>
This code is very similar to the above code except that we are looking at the courses within this category.<br />
Also note that this bit of code doesn't call add_category_to_custommenu recursivily, it doesn't need to as courses are the last bit we want to display on the menu within the category.

And that is it, time to tidy up and we're done.

==Finishing up==
All of the code is written now there is only last thing to do in order to tidy up however and that is to add the ''courses'' string that we used earlier... did you spot it?

This is of course very easy, open up '''moodle/theme/coursecategorymenu/lang/en/theme_coursecategorymenu.php''' and add the following:

<code php>
<?php

$string['courses'] = 'Courses';
</code>

And we're done. If you now browse to your site and change to the new theme you should see the Courses branch at the end of your custom menu that contains all of the categories, sub categories and courses for your site.

==Full source==
===config.php===
<code php>
<?php

$THEME->name = 'coursecategorymenu';
$THEME->parents = array('standard', 'base');
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>
===renderers.php===
<code php>
<?php

class theme_coursecategorymenu_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
global $CFG;

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

$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);

$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}

return parent::render_custom_menu($menu);
}

protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
}

}
</code>
===lang/en/theme_coursecategorymenu.php===
<code php>
<?php

$string['courses'] = 'Courses';
</code>

==See also==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]
* [[Development:Themes 2.0 extending the custom menu]]
* [http://developer.yahoo.com/yui/3/node-menunav/ YUI 3 Menunav component the custom menu uses]

User:Sam Hemelryk

2011-05-06T03:03:21Z

Samhemelryk:

Hello, I am a senior developer at Moodle and have been with the project since the June 2009.

For those interested I have written a tutorial on my Moodle development process with Git: [[User:Sam_Hemelryk/My_Moodle_Git_workflow]]

A short list of helpful documents I have created:

* [[Development:Themes 2.0]]
* [[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:Using jQuery with Moodle 2.0]]

Development:Themes 2.0 adding courses and categories to the custom menu

2011-05-06T03:02:43Z

Samhemelryk: /* See also */

Hello this is going to be a very brief tutorial on how to add a courses and categories tree to the custom menu.<br />
The reason for writing this tutorial is simply that this seems to be a request that is being made over and over again.

==Before we get started==
Please please please make sure you are familiar with the other Themes 2.0 tutorials before attempting this tutorial.

In particular I would recommend being familiar with the following documents and tutorials as I'm going to move through this tutorial at a fast pace.

* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]
* [[Development:Themes 2.0 extending the custom menu]]

Providing you are familiar with the above you should manage just fine with this tutorial and if you ever get stuck don't forget to ask in the theme's forums, there is always someone around who can help.

==Laying the ground work==
Alright I don't want this tutorial to drag out so get ready. For this tutorial I am just going to extend the standard theme, I'm going to make absolutely no changes to the design and layout of the theme or the custom menu I am ONLY going to add a list of courses and categories to it.

So to begin with within your Moodle themes directory create a new directory coursecategorymenu in which I want you to create three files, the first config.php which is obviously required, the second renderers.php as we are going to achieve this by overriding a renderer, and the third the English language file for this theme.

You should end up with:

* moodle/theme/coursecategorymenu
* moodle/theme/coursecategorymenu/config.php
* moodle/theme/coursecategorymenu/renderers.php
* moodle/theme/coursecategorymenu/lang/en/theme_coursecategorymenu.php

==config.php==
Obviously because all I want to base this theme off the standard theme and only override a renderer the config.php file is going to be VERY basic, so much so that I'm not going to go into details about it, as you've read the recommended tutorials you will already be completely familiar with everything it is doing.

<code php>
<?php

$THEME->name = 'coursecategorymenu';
$THEME->parents = array('standard', 'base');
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>

==renderers.php==
This is of course where the magic is going to happen.

In my case I want to add a branch to the end of the custom menu titled ''Courses'' and then I want to add the category and course structure to that branch.

So like the [[Development:Themes 2.0 extending the custom menu|extending the custom menu]] tutorial I will be overriding the core renderer and I will also be overriding the render_custom_menu_method.

So the code for this:
<code php>
class theme_coursecategorymenu_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
// Our code will go here shortly
}

}
</code>

You'll notice that is identical to the starting code for the extending custom menu tutorial.

The difference comes in the code that we are going to populate it with:

<code php>
require_once($CFG->dirroot.'/course/lib.php');

$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);

$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}

return parent::render_custom_menu($menu);
</code>

So lets work through this code line by line:

<code php>
require_once($CFG->dirroot.'/course/lib.php');
</code>

This we need to do because we are going to use part of the course API, in particular a function called ''get_course_category_tree()'' that we'll look at shortly.
The function we want to use exists within the course lib file and in order to be sure its always available we need to include this file.

<code php>
$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);
</code>

This line adds the ''Courses'' branch to the custom menu into which we will add the category and course structure.

<code php>
$categorytree = get_course_category_tree();
</code>

This line is the main one to note, here we are calling a Moodle function that will return us a category and course tree, because all courses need to be within a category the initial return is an array of categories, each category in the array will have the properties of the category as well as two additional properties, the first property '''categories''' is an array containing all of this categories sub categories, and the second property '''courses''' is also an array containing all of the courses within this category.

<code php>
$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}
</code>

Now these lines of code deal with the initial array of categories returned by the ''get_course_category_tree'' function.

In this case we iterate of the initial categories and for each one we call a method of the renderer '''add_category_to_custommenu''' now those of you who are clued in will realise that this method doesn't exist yet... and you are correct - we need to write this method which is what we will look at next.<br />
As a heads up the reason that we need to write another method is because we need a method that we can call recursivily as there are potentially infinite category branches all contains sub categories and courses.

<code php>
return parent::render_custom_menu($menu);
</code>

The final line of code simply calls the original render_custom_menu method now that we have extended the custom menu as we want.

Now that we have looked at the render_custom_menu lets write the function we just talked about '''add_category_to_custommenu'''.<br />
This function as discussed above is special in that we intend to call it recursively, that means we want to call it once for EVERY category that exists in the tree. We will need to give it the categories parent menu item as well as the category object we want added.

Lets look at the code for this method:

<code php>
protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
}
</code>

Ok so that doesn't look too bad, as you've already read the extending custom menu tutorial you will be able to spot some of the things it is doing, none the less lets walk through the code.

<code php>
protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
.....
}
</code>

First up the function definition, this function is going to be private because only we need it and it is going to take two arguments, the first $parent has to be a custom_menu_item, the second $category has to be the category object.

The objective of this method is to add a category node to the custom menu, in regards to our arguments we want to add $category as a child of $parent.

<code php>
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
</code>

This line looks very familiar, here we are adding a node for the category to the $parent, we are also collecting the newly added node as $branch.

<code php>
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
</code>

Now this code is responsible for add the sub categories of this category to the menu as well, first we need to check that the categories property isn't empty (if it is there is nothing to add).
Assuming there are sub categories we need go through each of them and call this method on them so that they get added to the custom menu as well.<br />
This is called recursion.

<code php>
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
</code>
This code is very similar to the above code except that we are looking at the courses within this category.<br />
Also note that this bit of code doesn't call add_category_to_custommenu recursivily, it doesn't need to as courses are the last bit we want to display on the menu within the category.

And that is it, time to tidy up and we're done.

==Finishing up==
All of the code is written now there is only last thing to do in order to tidy up however and that is to add the ''courses'' string that we used earlier... did you spot it?

This is of course very easy, open up '''moodle/theme/coursecategorymenu/lang/en/theme_coursecategorymenu.php''' and add the following:

<code php>
<?php

$string['courses'] = 'Courses';
</code>

And we're done. If you now browse to your site and change to the new theme you should see the Courses branch at the end of your custom menu that contains all of the categories, sub categories and courses for your site.

==Full source==
===config.php===
<code php>
<?php

$THEME->name = 'coursecategorymenu';
$THEME->parents = array('standard', 'base');
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>
===renderers.php===
<code php>
<?php

class theme_coursecategorymenu_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
global $CFG;

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

$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);

$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}

return parent::render_custom_menu($menu);
}

protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
}

}
</code>
===lang/en/theme_coursecategorymenu.php===
<code php>
<?php

$string['courses'] = 'Courses';
</code>

==See also==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]
* [[Development:Themes 2.0 extending the custom menu]]
* [http://developer.yahoo.com/yui/3/node-menunav/ YUI 3 Menunav component the custom menu uses]

Development:Themes 2.0 extending the custom menu

2011-05-06T03:02:19Z

Samhemelryk: /* See also */

{{Template:Themes}}{{Moodle 2.0}}This is a quick tutorial that will quickly run you through extending the custom menu by overriding your theme's renderer.

This tutorial is primarily PHP coding, and ranges from is a moderate to advanced difficulty.

==Before we begin==
First things first you need to know a little something about the custom menu. As you are undoubtedly aware the custom menu is populated from a specially crafted lines that you enter within the custommenu admin setting on the theme settings page under appearance in the settings block. Once the admin has entered the custom menu items into the setting and saved them the following steps are what they go through in order to be displayed:
# The theme calls '''''$OUTPUT->custom_menu()''''' which is the core_renderers method responsible for producing the custom menu.
# core_renderer::custom_menu() does the following:
## Checks to make sure the admin has added custom menu items.
## Creates a new '''''custom_menu''''' object. When the custom menu object is created it turns what ever the admin entered into a structured array of information.
## Calls core_renderer::render_custom_menu and gives it the custom_menu object.
# core_renderer::render_custom_menu is where the magic happens, it does the following.
## First it checks to make sure custom menu contains items.
## Initialises the JavaScript for the custom menu, this is the YUI3 menunode component.
## Creates the HTML base of the custom menu
## Then iterates through all of the items and calls the custom menu and passes them to another function that will turn them into HTML correctly.

I'm going to stop there, as there is no need at this point to go into any more detail. Don't worry if you are a little lost, it will get clearer as we start working through code.

In this tutorial will we look at how to extend the theme's renderer in two different way.
# Add a dynamic My Courses branch to the custom menu that will display all of the courses a user is enrolled in.
# Get the custom menu to fetch strings from the language files rather than just static strings you type, allowing for a translatable custom menu.

Before you start into this tutorial you should have read the following tutorials I have written, or at least have a good knowledge of the the Moodle 2.0 theme engine and Moodle development.
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]

As this is a quick tutorial I am going to assume you have created a theme, tested it and got it all working, and are already well on your way to becoming a theme guru.

Because the pressure is on to get Moodle 2.0 out the door this will be a quick tutorial, please if you have any questions or need a hand ask in the theme's forum.

==Getting started==
Alright, as you have already have your theme ready to go preparation is pretty simple, we are going to go through and create (if you haven't already) the following files:
* theme/themename/lib.php
* theme/themename/renderers.php
* theme/themename/lang/en/themename.php

Next step open up your themes config.php file and add the following configuration option to it (at the bottom):
<code php>
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>

If you've already got a custom renderer you will already have this line.

And thats it! now we move on to extending the custom menu.

==Adding the My Courses branch==
So the point of this extension is to add a '''My Courses''' branch to the end of the custom menu.

The plan is to have the my courses branch and then within that branch have an entry for every course the user is enrolled in, much the same as the my courses branch of the navigation.

In order to achieve this we need to add some items to the custom menu, the my courses branch and all of the courses within it. We can do this overriding the core_renderers '''render_custom_menu''' method, of more accuratly create our own render_custom_menu method that adds our items and then calls the original. Remember we only need to add items, we don't need to change what is being produced.

So within our renderers.php file add the following code:
<code php>
class theme_themename_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
// Our code will go here shortly
}

}
</code>

So that is pretty simple right?!

Here we are defining our core_renderer which will contain our overridden method ''render_custom_menu'' which we have also defined there.
Note the definition of the render_custom_menu must be the same as the original, this means it must be '''protected''' and it must take one argument '''custom_menu $menu'''.

Next step is to write the code for our render_custom_menu method. As stated above we want to add a branch and courses to the end of it which we can do with the following bit of code:
<code php>
$mycourses = $this->page->navigation->get('mycourses');

if (isloggedin() && $mycourses && $mycourses->has_children()) {
$branchlabel = get_string('mycourses');
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = 10000;

$branch = $menu->add($branchlabel, $branchurl, $branchtitle, $branchsort);

foreach ($mycourses->children as $coursenode) {
$branch->add($coursenode->get_content(), $coursenode->action, $coursenode->get_title());
}
}

return parent::render_custom_menu($menu);
</code>

So how this all works....
<code php>
$mycourses = $this->page->navigation->get('mycourses');
</code>
This line is a little bit of smarts, what we are doing is getting the mycourses branch from the navigation. We could make all of the database calls and work it all out ourselves but this will be much better for performance and is easier!

The next line of code is an ''if'' statement that checks three things
# The user is logged in, you must be logged in to see your courses.
# That we have a mycourses object, if the user isn't enrolled in anything they won't have a mycourses object.
# The the mycourses object has children, if it exists it should but it is better to be safe than get errors.

Within the if statement we are doing two main things happening, the first is to add the branch to the menu:
<code php>
$branchlabel = get_string('mycourses');
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = 10000;

$branch = $menu->add($branchlabel, $branchurl, $branchtitle, $branchsort);
</code>
When adding a new branch we need to give it three things:
# A label '''$branchlabel'''.
# A URL '''$branchurl'''.
# A title '''$branchtitle''' in this case I have just set it to the same as $branchlabel because I am lazy, you can make it anything you want.
# A sort order '''$branchsort''' this just needs to be high enough that it ends up on last place where we want it. Make it small to put it at the front.

The final line of code from above simply adds it to the menu and collects a reference to it so that we can add courses to it.

The second thing being done in the if statement is iterate through all of the courses in the mycourses object and add them to the branch. That is done with the following bit of code:
<code php>
foreach ($mycourses->children as $coursenode) {
$branch->add($coursenode->get_content(), $coursenode->action, $coursenode->get_title());
}
</code>
So here we go through all of the mycourses objects children (which we know will be courses) and for each one we add an item to the branch.
When adding items here, like above, we need to give it the following:
# A label '''$coursenode->get_content()''' returns us the text in the navigation node.
# A url '''$coursenode->action''' which is the URL for the node.
# A title '''$coursenode->get_title()'''.

In this case we don't need to set a sort order because the navigation has already ordered them correctly!

So now we are through the if statement and there is only one line of code left:
<code php>
return parent::render_custom_menu($menu);
</code>

This line of code simply calls the original '''core_renderer::render_custom_menu''' method to do all of the remaining work. Because we don't need to change the display at all we don't need to redo what it does, we can just use it!.

How easy way that?! it's all done, if you open you site in your browser and log in the custom menu should now contain a my courses branch (providing you are enrolled in courses).

==Loading labels from language files==
If you run a site that is available in more than one language '''and''' you want to make use of the custom menu then you will probably be very interested in this.

The idea behind this extension is to load the labels and titles that get shown in the custom menu from the theme's language files rather than having just the fixed strings you type into the admin setting.

In order to achieve this we need to do somehow override the custom_menu_item class so that it loads the strings from the database if they match a special pattern. We can then update the admin setting to use our patter and wallah! things should load from the language files.

What makes this tricky is that we can't just override the custom_menu_item class, we also need to override the thing that makes create custom_menu_item instances which in this case is the core_renderer::render_custom_menu_item method.

===Overriding the custom_menu_item class===
Within your themes lib.php file add the following lines of code:
<code php>
class transmuted_custom_menu_item extends custom_menu_item {
public function __construct(custom_menu_item $menunode) {
// Our code will go here
}
}
</code>
What we have done here is create a overridden custom_menu_item class called '''transmuted_custom_menu_item'''.
Within that class we are overriding the constructor, the constructor will be given the original menu item and we will need to instatiate this object with the properties of the original.
Once we have instantiated it with the properties of the original we can alter then as we like.

Next we need to write the contents of the ''__construct'' method:
<code php>
parent::__construct($menunode->get_text(), $menunode->get_url(), $menunode->get_title(), $menunode->get_sort_order(), $menunode->get_parent());
$this->children = $menunode->get_children();

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->text, $matches)) {
try {
$this->text = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->text = $matches[1];
}
}

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->title, $matches)) {
try {
$this->title = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->title = $matches[1];
}
}
</code>

So there are essentially four things going on here.

Firs we need to populate this object with the properties of the original item. We do this by calling the original constructor with $menunode's properties as shown below.
<code php>
parent::__construct($menunode->get_text(), $menunode->get_url(), $menunode->get_title(), $menunode->get_sort_order(), $menunode->get_parent());
</code>

Next we need to copy the properties that arn't included in the original constructor, in this case there is only one '''$this->children'''. This should be an array of all of this items children (sub items).
<code php>
$this->children = $menunode->get_children();
</code>

Now that we have all the properties set up we can modify them. In our case we want to check if the items label and title match a special pattern and if they do we want to fetch them from the language file instead.
The special pattern is '''<nowiki>[[stringname]]</nowiki>''' where stringname is the name of the string that we want to get from the language file.
<code php>
$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->text, $matches)) {
try {
$this->text = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->text = $matches[1];
}
}
</code>
In the code above we do the following:
# Create an array $matches which will hold the stringname if the label matches the pattern.
# We attempt to match the label to the pattern. If it does the $matches array now contains the stringname.
# If it did match we call get string as shown.

The third and final thing is to do the above again but this time for the title.

With that done our transmutable_custom_menu_item class is complete. Next step is to make use of it.

===Overriding render_custom_menu_item===
The next step is make use of the transmutable_custom_menu_item class we created previously.

We can do this by overriding the '''core_renderer::render_custom_menu_item''' method within our renderers.php file as shown below.
<code php>
protected function render_custom_menu_item(custom_menu_item $menunode) {
$transmutedmenunode = new transmuted_custom_menu_item($menunode);
return parent::render_custom_menu_item($transmutedmenunode);
}
</code>
This is pretty simply, essentially we are using our transmuted_custom_menu_item class like a façade to the original custom_menu_item class by creating a new transmuted instance using the original.
Once we have the transmuted object we can call the original render_custom_menu_item method with it.

And that is it! Congratulations if you got it this far.

The only thing left to do is add strings to your themes language file as required!

==Complete source==
<code php>
// theme/themename/renderers.php

class theme_themename_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {

$mycourses = $this->page->navigation->get('mycourses');

if (isloggedin() && $mycourses && $mycourses->has_children()) {
$branchlabel = get_string('mycourses');
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = 10000;

$branch = $menu->add($branchlabel, $branchurl, $branchtitle, $branchsort);

foreach ($mycourses->children as $coursenode) {
$branch->add($coursenode->get_content(), $coursenode->action, $coursenode->get_title());
}
}

return parent::render_custom_menu($menu);
}

protected function render_custom_menu_item(custom_menu_item $menunode) {
$transmutedmenunode = new transmuted_custom_menu_item($menunode);
return parent::render_custom_menu_item($transmutedmenunode);
}

}
</code>

<code php>
// theme/themename/lib.php

class transmuted_custom_menu_item extends custom_menu_item {
public function __construct(custom_menu_item $menunode) {
parent::__construct($menunode->get_text(), $menunode->get_url(), $menunode->get_title(), $menunode->get_sort_order(), $menunode->get_parent());
$this->children = $menunode->get_children();

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->text, $matches)) {
try {
$this->text = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->text = $matches[1];
}
}

$matches = array();
if (preg_match('/^\[\[([a-zA-Z0-9\-\_\:]+)\]\]$/', $this->title, $matches)) {
try {
$this->title = get_string($matches[1], 'theme_themename');
} catch (Exception $e) {
$this->title = $matches[1];
}
}
}
}
</code>
==See also==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]
* [[Development:Themes 2.0 adding courses and categories to the custom menu]]
* [http://developer.yahoo.com/yui/3/node-menunav/ YUI 3 Menunav component the custom menu uses]

Development:Themes 2.0

2011-05-06T03:01:57Z

Samhemelryk: /* See also */

{{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 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]]

Development:Themes 2.0 adding courses and categories to the custom menu

2011-05-06T02:55:54Z

Samhemelryk: /* lang/en/theme_ */

Hello this is going to be a very brief tutorial on how to add a courses and categories tree to the custom menu.<br />
The reason for writing this tutorial is simply that this seems to be a request that is being made over and over again.

==Before we get started==
Please please please make sure you are familiar with the other Themes 2.0 tutorials before attempting this tutorial.

In particular I would recommend being familiar with the following documents and tutorials as I'm going to move through this tutorial at a fast pace.

* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]
* [[Development:Themes 2.0 extending the custom menu]]

Providing you are familiar with the above you should manage just fine with this tutorial and if you ever get stuck don't forget to ask in the theme's forums, there is always someone around who can help.

==Laying the ground work==
Alright I don't want this tutorial to drag out so get ready. For this tutorial I am just going to extend the standard theme, I'm going to make absolutely no changes to the design and layout of the theme or the custom menu I am ONLY going to add a list of courses and categories to it.

So to begin with within your Moodle themes directory create a new directory coursecategorymenu in which I want you to create three files, the first config.php which is obviously required, the second renderers.php as we are going to achieve this by overriding a renderer, and the third the English language file for this theme.

You should end up with:

* moodle/theme/coursecategorymenu
* moodle/theme/coursecategorymenu/config.php
* moodle/theme/coursecategorymenu/renderers.php
* moodle/theme/coursecategorymenu/lang/en/theme_coursecategorymenu.php

==config.php==
Obviously because all I want to base this theme off the standard theme and only override a renderer the config.php file is going to be VERY basic, so much so that I'm not going to go into details about it, as you've read the recommended tutorials you will already be completely familiar with everything it is doing.

<code php>
<?php

$THEME->name = 'coursecategorymenu';
$THEME->parents = array('standard', 'base');
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>

==renderers.php==
This is of course where the magic is going to happen.

In my case I want to add a branch to the end of the custom menu titled ''Courses'' and then I want to add the category and course structure to that branch.

So like the [[Development:Themes 2.0 extending the custom menu|extending the custom menu]] tutorial I will be overriding the core renderer and I will also be overriding the render_custom_menu_method.

So the code for this:
<code php>
class theme_coursecategorymenu_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
// Our code will go here shortly
}

}
</code>

You'll notice that is identical to the starting code for the extending custom menu tutorial.

The difference comes in the code that we are going to populate it with:

<code php>
require_once($CFG->dirroot.'/course/lib.php');

$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);

$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}

return parent::render_custom_menu($menu);
</code>

So lets work through this code line by line:

<code php>
require_once($CFG->dirroot.'/course/lib.php');
</code>

This we need to do because we are going to use part of the course API, in particular a function called ''get_course_category_tree()'' that we'll look at shortly.
The function we want to use exists within the course lib file and in order to be sure its always available we need to include this file.

<code php>
$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);
</code>

This line adds the ''Courses'' branch to the custom menu into which we will add the category and course structure.

<code php>
$categorytree = get_course_category_tree();
</code>

This line is the main one to note, here we are calling a Moodle function that will return us a category and course tree, because all courses need to be within a category the initial return is an array of categories, each category in the array will have the properties of the category as well as two additional properties, the first property '''categories''' is an array containing all of this categories sub categories, and the second property '''courses''' is also an array containing all of the courses within this category.

<code php>
$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}
</code>

Now these lines of code deal with the initial array of categories returned by the ''get_course_category_tree'' function.

In this case we iterate of the initial categories and for each one we call a method of the renderer '''add_category_to_custommenu''' now those of you who are clued in will realise that this method doesn't exist yet... and you are correct - we need to write this method which is what we will look at next.<br />
As a heads up the reason that we need to write another method is because we need a method that we can call recursivily as there are potentially infinite category branches all contains sub categories and courses.

<code php>
return parent::render_custom_menu($menu);
</code>

The final line of code simply calls the original render_custom_menu method now that we have extended the custom menu as we want.

Now that we have looked at the render_custom_menu lets write the function we just talked about '''add_category_to_custommenu'''.<br />
This function as discussed above is special in that we intend to call it recursively, that means we want to call it once for EVERY category that exists in the tree. We will need to give it the categories parent menu item as well as the category object we want added.

Lets look at the code for this method:

<code php>
protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
}
</code>

Ok so that doesn't look too bad, as you've already read the extending custom menu tutorial you will be able to spot some of the things it is doing, none the less lets walk through the code.

<code php>
protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
.....
}
</code>

First up the function definition, this function is going to be private because only we need it and it is going to take two arguments, the first $parent has to be a custom_menu_item, the second $category has to be the category object.

The objective of this method is to add a category node to the custom menu, in regards to our arguments we want to add $category as a child of $parent.

<code php>
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
</code>

This line looks very familiar, here we are adding a node for the category to the $parent, we are also collecting the newly added node as $branch.

<code php>
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
</code>

Now this code is responsible for add the sub categories of this category to the menu as well, first we need to check that the categories property isn't empty (if it is there is nothing to add).
Assuming there are sub categories we need go through each of them and call this method on them so that they get added to the custom menu as well.<br />
This is called recursion.

<code php>
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
</code>
This code is very similar to the above code except that we are looking at the courses within this category.<br />
Also note that this bit of code doesn't call add_category_to_custommenu recursivily, it doesn't need to as courses are the last bit we want to display on the menu within the category.

And that is it, time to tidy up and we're done.

==Finishing up==
All of the code is written now there is only last thing to do in order to tidy up however and that is to add the ''courses'' string that we used earlier... did you spot it?

This is of course very easy, open up '''moodle/theme/coursecategorymenu/lang/en/theme_coursecategorymenu.php''' and add the following:

<code php>
<?php

$string['courses'] = 'Courses';
</code>

And we're done. If you now browse to your site and change to the new theme you should see the Courses branch at the end of your custom menu that contains all of the categories, sub categories and courses for your site.

==Full source==
===config.php===
<code php>
<?php

$THEME->name = 'coursecategorymenu';
$THEME->parents = array('standard', 'base');
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>
===renderers.php===
<code php>
<?php

class theme_coursecategorymenu_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
global $CFG;

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

$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);

$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}

return parent::render_custom_menu($menu);
}

protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
}

}
</code>
===lang/en/theme_coursecategorymenu.php===
<code php>
<?php

$string['courses'] = 'Courses';
</code>

==See also==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]
* [http://developer.yahoo.com/yui/3/node-menunav/ YUI 3 Menunav component the custom menu uses]

Development:Themes 2.0 adding courses and categories to the custom menu

2011-05-06T02:55:38Z

Samhemelryk: Created page with "Hello this is going to be a very brief tutorial on how to add a courses and categories tree to the custom menu.<br /> The reason for writing this tutorial is simply that this see..."

Hello this is going to be a very brief tutorial on how to add a courses and categories tree to the custom menu.<br />
The reason for writing this tutorial is simply that this seems to be a request that is being made over and over again.

==Before we get started==
Please please please make sure you are familiar with the other Themes 2.0 tutorials before attempting this tutorial.

In particular I would recommend being familiar with the following documents and tutorials as I'm going to move through this tutorial at a fast pace.

* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]
* [[Development:Themes 2.0 extending the custom menu]]

Providing you are familiar with the above you should manage just fine with this tutorial and if you ever get stuck don't forget to ask in the theme's forums, there is always someone around who can help.

==Laying the ground work==
Alright I don't want this tutorial to drag out so get ready. For this tutorial I am just going to extend the standard theme, I'm going to make absolutely no changes to the design and layout of the theme or the custom menu I am ONLY going to add a list of courses and categories to it.

So to begin with within your Moodle themes directory create a new directory coursecategorymenu in which I want you to create three files, the first config.php which is obviously required, the second renderers.php as we are going to achieve this by overriding a renderer, and the third the English language file for this theme.

You should end up with:

* moodle/theme/coursecategorymenu
* moodle/theme/coursecategorymenu/config.php
* moodle/theme/coursecategorymenu/renderers.php
* moodle/theme/coursecategorymenu/lang/en/theme_coursecategorymenu.php

==config.php==
Obviously because all I want to base this theme off the standard theme and only override a renderer the config.php file is going to be VERY basic, so much so that I'm not going to go into details about it, as you've read the recommended tutorials you will already be completely familiar with everything it is doing.

<code php>
<?php

$THEME->name = 'coursecategorymenu';
$THEME->parents = array('standard', 'base');
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>

==renderers.php==
This is of course where the magic is going to happen.

In my case I want to add a branch to the end of the custom menu titled ''Courses'' and then I want to add the category and course structure to that branch.

So like the [[Development:Themes 2.0 extending the custom menu|extending the custom menu]] tutorial I will be overriding the core renderer and I will also be overriding the render_custom_menu_method.

So the code for this:
<code php>
class theme_coursecategorymenu_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
// Our code will go here shortly
}

}
</code>

You'll notice that is identical to the starting code for the extending custom menu tutorial.

The difference comes in the code that we are going to populate it with:

<code php>
require_once($CFG->dirroot.'/course/lib.php');

$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);

$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}

return parent::render_custom_menu($menu);
</code>

So lets work through this code line by line:

<code php>
require_once($CFG->dirroot.'/course/lib.php');
</code>

This we need to do because we are going to use part of the course API, in particular a function called ''get_course_category_tree()'' that we'll look at shortly.
The function we want to use exists within the course lib file and in order to be sure its always available we need to include this file.

<code php>
$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);
</code>

This line adds the ''Courses'' branch to the custom menu into which we will add the category and course structure.

<code php>
$categorytree = get_course_category_tree();
</code>

This line is the main one to note, here we are calling a Moodle function that will return us a category and course tree, because all courses need to be within a category the initial return is an array of categories, each category in the array will have the properties of the category as well as two additional properties, the first property '''categories''' is an array containing all of this categories sub categories, and the second property '''courses''' is also an array containing all of the courses within this category.

<code php>
$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}
</code>

Now these lines of code deal with the initial array of categories returned by the ''get_course_category_tree'' function.

In this case we iterate of the initial categories and for each one we call a method of the renderer '''add_category_to_custommenu''' now those of you who are clued in will realise that this method doesn't exist yet... and you are correct - we need to write this method which is what we will look at next.<br />
As a heads up the reason that we need to write another method is because we need a method that we can call recursivily as there are potentially infinite category branches all contains sub categories and courses.

<code php>
return parent::render_custom_menu($menu);
</code>

The final line of code simply calls the original render_custom_menu method now that we have extended the custom menu as we want.

Now that we have looked at the render_custom_menu lets write the function we just talked about '''add_category_to_custommenu'''.<br />
This function as discussed above is special in that we intend to call it recursively, that means we want to call it once for EVERY category that exists in the tree. We will need to give it the categories parent menu item as well as the category object we want added.

Lets look at the code for this method:

<code php>
protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
}
</code>

Ok so that doesn't look too bad, as you've already read the extending custom menu tutorial you will be able to spot some of the things it is doing, none the less lets walk through the code.

<code php>
protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
.....
}
</code>

First up the function definition, this function is going to be private because only we need it and it is going to take two arguments, the first $parent has to be a custom_menu_item, the second $category has to be the category object.

The objective of this method is to add a category node to the custom menu, in regards to our arguments we want to add $category as a child of $parent.

<code php>
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
</code>

This line looks very familiar, here we are adding a node for the category to the $parent, we are also collecting the newly added node as $branch.

<code php>
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
</code>

Now this code is responsible for add the sub categories of this category to the menu as well, first we need to check that the categories property isn't empty (if it is there is nothing to add).
Assuming there are sub categories we need go through each of them and call this method on them so that they get added to the custom menu as well.<br />
This is called recursion.

<code php>
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
</code>
This code is very similar to the above code except that we are looking at the courses within this category.<br />
Also note that this bit of code doesn't call add_category_to_custommenu recursivily, it doesn't need to as courses are the last bit we want to display on the menu within the category.

And that is it, time to tidy up and we're done.

==Finishing up==
All of the code is written now there is only last thing to do in order to tidy up however and that is to add the ''courses'' string that we used earlier... did you spot it?

This is of course very easy, open up '''moodle/theme/coursecategorymenu/lang/en/theme_coursecategorymenu.php''' and add the following:

<code php>
<?php

$string['courses'] = 'Courses';
</code>

And we're done. If you now browse to your site and change to the new theme you should see the Courses branch at the end of your custom menu that contains all of the categories, sub categories and courses for your site.

==Full source==
===config.php===
<code php>
<?php

$THEME->name = 'coursecategorymenu';
$THEME->parents = array('standard', 'base');
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>
===renderers.php===
<code php>
<?php

class theme_coursecategorymenu_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
global $CFG;

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

$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);

$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}

return parent::render_custom_menu($menu);
}

protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
}

}
</code>
===lang/en/theme_===
<code php>
<?php

$string['courses'] = 'Courses';
</code>

==See also==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]
* [http://developer.yahoo.com/yui/3/node-menunav/ YUI 3 Menunav component the custom menu uses]

User:Sam Hemelryk

2011-04-19T03:28:14Z

Samhemelryk:

Hello, I am a senior developer at Moodle and have been with the project since the June 2009.

For those interested I have written a tutorial on my Moodle development process with Git: [[User:Sam_Hemelryk/My_Moodle_Git_workflow]]

A short list of helpful documents I have created:

* [[Development:Themes 2.0]]
* [[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:Using jQuery with Moodle 2.0]]

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T03:23:23Z

Samhemelryk: /* What to do when your work gets rejected */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

I would '''strongly''' suggest while learning Moodle development that you use [[User:Tim Hunt|Tim Hunt's]] fantastic [https://github.com/timhunt/moodle-local_codechecker Code Checker] plugin.<br />
You'll find information on how to use it within its README file and it will pick up many of the things that may lead to your work being rejected.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating PULL requests==
Now that you've got a branch with changes for your MDL issue its time to create some PULL requests to get it integrated.

===Creating a PULL request for the master branch===

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

====Summary====
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

====Affects Versions====
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

====Security level====
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

====Pull from repository====
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

====Pull branch====
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

====Pull Diff URL====
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

====Description====
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

====Components====
Select general from the components list, general is the only option.

====Finishing up====
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.<br />I should add that the comment isn't really required. It's just something I personally like doing.

Time to create the PULL request for the other branches.

===Creating the PULL request for MOODLE_20_STABLE===
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Resolving the issue==
The final step for the MDL issue now that you have created the two PULL requests is to Resolve the issue (do not close it, just resolve).

You can do this by logging into tracker, browsing to the MDL issue, and clicking the resolve button.

If your fixes are integrated the tester will close the issue, otherwise if it doesn't get integrated someone will reopen the MDL.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications.
You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==So your work got rejected... what now?==
First up don't give up, we (Moodle integrators) don't just reject code willy-nilly, we always provide a reason.

There are a couple of different paths that this may lead you down:
# More work needed: This happens if you have fixed half of the bug, or some of the bugs, but not all/completely. In this case you just need to finish off the MDL and then create new PULL requests.
# Bugs + white space issues: If this is the case you need to fix up what ever was spotted and then create new PULL requests.
# Not appropriate for a stable branch: This happens if the integrator decides that your work shouldn't get into the STABLE branch but is still OK for the master branch. Things like new features or improvements are likely to head down this path. If this is the case then everything is done, your work will have been integrated into master and you will just have to wait until the next major release (2.1, 2.2 etc).
# Not appropriate for core: If this happens it means that the integrator has decided that the work you've done isn't suitable to go into the main Moodle code base. If this is the case and you still want to use your branches that is fine, just leave them up on your github account and whenever you need to use them just merge your branch into your sites repository.

==The extra mile==
Now as many of you may have guessed by the time you are working on several different issues and managing several repositories the process I've described here seems VERY repetitive. And it '''IS!'''.

If you talk to any HQ developer they will tell you they deal with it in their own way, anything from scripts, to custom config files, through to virtual machine snapshots.

Personally I have a couple of bash scripts that I wrote to help me manage my workflow.

The first script I use I run after each weekly release and it does the following things:

* Moves to each repository and does the following
*# Fetches all remote changes
*# Checks whether it is safe to update my local main release branches and does that if it is safe
*# Updates all main release branches on my github account

The second script I run on every site that I have installed, it does the following

* Goes to each site I have installed and does the following
*# Overwrites the database with a stable snapshot
*# Overwrites the moodle data directory with a stable snapshot taken at the same time as the database one.
*# Upgrades the moodle site if required
*# Takes a snapshot of the database and Moodle data directory.

The third script I run whenever I start working on a new issue and it restores the stable snapshot of a sites database and moodle data directory.

These three scripts allow me to very easily ensure I am working with the latest changes and that I can easily restore to a point I know is stable and safe.

There was a fourth script I used to use but don't any more that also rebased any unmerged branches however I found it to be far to problematic and I prefer to do it myself so that I know exactly what is going on.

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.
* [[Development:Git tips]] Moodle docs page with a few handy tips about using Git for Moodle development.

I you're looking to read/buy a book on Git I'd strongly recommend [http://progit.org/ Pro Git]. I certainly found that the most useful book I read.

[[Category:Git]]

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T03:16:40Z

Samhemelryk: /* Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

I would '''strongly''' suggest while learning Moodle development that you use [[User:Tim Hunt|Tim Hunt's]] fantastic [https://github.com/timhunt/moodle-local_codechecker Code Checker] plugin.<br />
You'll find information on how to use it within its README file and it will pick up many of the things that may lead to your work being rejected.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating PULL requests==
Now that you've got a branch with changes for your MDL issue its time to create some PULL requests to get it integrated.

===Creating a PULL request for the master branch===

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

====Summary====
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

====Affects Versions====
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

====Security level====
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

====Pull from repository====
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

====Pull branch====
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

====Pull Diff URL====
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

====Description====
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

====Components====
Select general from the components list, general is the only option.

====Finishing up====
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.<br />I should add that the comment isn't really required. It's just something I personally like doing.

Time to create the PULL request for the other branches.

===Creating the PULL request for MOODLE_20_STABLE===
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Resolving the issue==
The final step for the MDL issue now that you have created the two PULL requests is to Resolve the issue (do not close it, just resolve).

You can do this by logging into tracker, browsing to the MDL issue, and clicking the resolve button.

If your fixes are integrated the tester will close the issue, otherwise if it doesn't get integrated someone will reopen the MDL.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications.
You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==What to do when your work gets rejected==

==The extra mile==
Now as many of you may have guessed by the time you are working on several different issues and managing several repositories the process I've described here seems VERY repetitive. And it '''IS!'''.

If you talk to any HQ developer they will tell you they deal with it in their own way, anything from scripts, to custom config files, through to virtual machine snapshots.

Personally I have a couple of bash scripts that I wrote to help me manage my workflow.

The first script I use I run after each weekly release and it does the following things:

* Moves to each repository and does the following
*# Fetches all remote changes
*# Checks whether it is safe to update my local main release branches and does that if it is safe
*# Updates all main release branches on my github account

The second script I run on every site that I have installed, it does the following

* Goes to each site I have installed and does the following
*# Overwrites the database with a stable snapshot
*# Overwrites the moodle data directory with a stable snapshot taken at the same time as the database one.
*# Upgrades the moodle site if required
*# Takes a snapshot of the database and Moodle data directory.

The third script I run whenever I start working on a new issue and it restores the stable snapshot of a sites database and moodle data directory.

These three scripts allow me to very easily ensure I am working with the latest changes and that I can easily restore to a point I know is stable and safe.

There was a fourth script I used to use but don't any more that also rebased any unmerged branches however I found it to be far to problematic and I prefer to do it myself so that I know exactly what is going on.

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.
* [[Development:Git tips]] Moodle docs page with a few handy tips about using Git for Moodle development.

I you're looking to read/buy a book on Git I'd strongly recommend [http://progit.org/ Pro Git]. I certainly found that the most useful book I read.

[[Category:Git]]

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T03:16:04Z

Samhemelryk: /* Creating the PULL request for MOODLE_20_STABLE */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

I would '''strongly''' suggest while learning Moodle development that you use [[User:Tim Hunt|Tim Hunt's]] fantastic [https://github.com/timhunt/moodle-local_codechecker Code Checker] plugin.<br />
You'll find information on how to use it within its README file and it will pick up many of the things that may lead to your work being rejected.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating PULL requests==
Now that you've got a branch with changes for your MDL issue its time to create some PULL requests to get it integrated.

===Creating a PULL request for the master branch===

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

====Summary====
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

====Affects Versions====
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

====Security level====
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

====Pull from repository====
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

====Pull branch====
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

====Pull Diff URL====
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

====Description====
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

====Components====
Select general from the components list, general is the only option.

====Finishing up====
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.<br />I should add that the comment isn't really required. It's just something I personally like doing.

Time to create the PULL request for the other branches.

===Creating the PULL request for MOODLE_20_STABLE===
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Resolving the issue==
The final step for the MDL issue now that you have created the two PULL requests is to Resolve the issue (do not close it, just resolve).

You can do this by logging into tracker, browsing to the MDL issue, and clicking the resolve button.

If your fixes are integrated the tester will close the issue, otherwise if it doesn't get integrated someone will reopen the MDL.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications.
You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==The extra mile==
Now as many of you may have guessed by the time you are working on several different issues and managing several repositories the process I've described here seems VERY repetitive. And it '''IS!'''.

If you talk to any HQ developer they will tell you they deal with it in their own way, anything from scripts, to custom config files, through to virtual machine snapshots.

Personally I have a couple of bash scripts that I wrote to help me manage my workflow.

The first script I use I run after each weekly release and it does the following things:

* Moves to each repository and does the following
*# Fetches all remote changes
*# Checks whether it is safe to update my local main release branches and does that if it is safe
*# Updates all main release branches on my github account

The second script I run on every site that I have installed, it does the following

* Goes to each site I have installed and does the following
*# Overwrites the database with a stable snapshot
*# Overwrites the moodle data directory with a stable snapshot taken at the same time as the database one.
*# Upgrades the moodle site if required
*# Takes a snapshot of the database and Moodle data directory.

The third script I run whenever I start working on a new issue and it restores the stable snapshot of a sites database and moodle data directory.

These three scripts allow me to very easily ensure I am working with the latest changes and that I can easily restore to a point I know is stable and safe.

There was a fourth script I used to use but don't any more that also rebased any unmerged branches however I found it to be far to problematic and I prefer to do it myself so that I know exactly what is going on.

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.
* [[Development:Git tips]] Moodle docs page with a few handy tips about using Git for Moodle development.

I you're looking to read/buy a book on Git I'd strongly recommend [http://progit.org/ Pro Git]. I certainly found that the most useful book I read.

[[Category:Git]]

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T03:15:48Z

Samhemelryk: /* Creating a PULL request for the master branch */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

I would '''strongly''' suggest while learning Moodle development that you use [[User:Tim Hunt|Tim Hunt's]] fantastic [https://github.com/timhunt/moodle-local_codechecker Code Checker] plugin.<br />
You'll find information on how to use it within its README file and it will pick up many of the things that may lead to your work being rejected.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating PULL requests==
Now that you've got a branch with changes for your MDL issue its time to create some PULL requests to get it integrated.

===Creating a PULL request for the master branch===

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

====Summary====
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

====Affects Versions====
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

====Security level====
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

====Pull from repository====
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

====Pull branch====
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

====Pull Diff URL====
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

====Description====
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

====Components====
Select general from the components list, general is the only option.

====Finishing up====
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.<br />I should add that the comment isn't really required. It's just something I personally like doing.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Resolving the issue==
The final step for the MDL issue now that you have created the two PULL requests is to Resolve the issue (do not close it, just resolve).

You can do this by logging into tracker, browsing to the MDL issue, and clicking the resolve button.

If your fixes are integrated the tester will close the issue, otherwise if it doesn't get integrated someone will reopen the MDL.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications.
You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==The extra mile==
Now as many of you may have guessed by the time you are working on several different issues and managing several repositories the process I've described here seems VERY repetitive. And it '''IS!'''.

If you talk to any HQ developer they will tell you they deal with it in their own way, anything from scripts, to custom config files, through to virtual machine snapshots.

Personally I have a couple of bash scripts that I wrote to help me manage my workflow.

The first script I use I run after each weekly release and it does the following things:

* Moves to each repository and does the following
*# Fetches all remote changes
*# Checks whether it is safe to update my local main release branches and does that if it is safe
*# Updates all main release branches on my github account

The second script I run on every site that I have installed, it does the following

* Goes to each site I have installed and does the following
*# Overwrites the database with a stable snapshot
*# Overwrites the moodle data directory with a stable snapshot taken at the same time as the database one.
*# Upgrades the moodle site if required
*# Takes a snapshot of the database and Moodle data directory.

The third script I run whenever I start working on a new issue and it restores the stable snapshot of a sites database and moodle data directory.

These three scripts allow me to very easily ensure I am working with the latest changes and that I can easily restore to a point I know is stable and safe.

There was a fourth script I used to use but don't any more that also rebased any unmerged branches however I found it to be far to problematic and I prefer to do it myself so that I know exactly what is going on.

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.
* [[Development:Git tips]] Moodle docs page with a few handy tips about using Git for Moodle development.

I you're looking to read/buy a book on Git I'd strongly recommend [http://progit.org/ Pro Git]. I certainly found that the most useful book I read.

[[Category:Git]]

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T03:10:11Z

Samhemelryk: /* Creating the PULL request for MOODLE_20_STABLE */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

I would '''strongly''' suggest while learning Moodle development that you use [[User:Tim Hunt|Tim Hunt's]] fantastic [https://github.com/timhunt/moodle-local_codechecker Code Checker] plugin.<br />
You'll find information on how to use it within its README file and it will pick up many of the things that may lead to your work being rejected.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating a PULL request for the master branch==

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

===Summary===
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

===Affects Versions===
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

===Security level===
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

===Pull from repository===
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

===Pull branch===
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

===Pull Diff URL===
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

===Description===
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

===Components===
Select general from the components list, general is the only option.

===Finishing up===
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.<br />I should add that the comment isn't really required. It's just something I personally like doing.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Resolving the issue==
The final step for the MDL issue now that you have created the two PULL requests is to Resolve the issue (do not close it, just resolve).

You can do this by logging into tracker, browsing to the MDL issue, and clicking the resolve button.

If your fixes are integrated the tester will close the issue, otherwise if it doesn't get integrated someone will reopen the MDL.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications.
You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==The extra mile==
Now as many of you may have guessed by the time you are working on several different issues and managing several repositories the process I've described here seems VERY repetitive. And it '''IS!'''.

If you talk to any HQ developer they will tell you they deal with it in their own way, anything from scripts, to custom config files, through to virtual machine snapshots.

Personally I have a couple of bash scripts that I wrote to help me manage my workflow.

The first script I use I run after each weekly release and it does the following things:

* Moves to each repository and does the following
*# Fetches all remote changes
*# Checks whether it is safe to update my local main release branches and does that if it is safe
*# Updates all main release branches on my github account

The second script I run on every site that I have installed, it does the following

* Goes to each site I have installed and does the following
*# Overwrites the database with a stable snapshot
*# Overwrites the moodle data directory with a stable snapshot taken at the same time as the database one.
*# Upgrades the moodle site if required
*# Takes a snapshot of the database and Moodle data directory.

The third script I run whenever I start working on a new issue and it restores the stable snapshot of a sites database and moodle data directory.

These three scripts allow me to very easily ensure I am working with the latest changes and that I can easily restore to a point I know is stable and safe.

There was a fourth script I used to use but don't any more that also rebased any unmerged branches however I found it to be far to problematic and I prefer to do it myself so that I know exactly what is going on.

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.
* [[Development:Git tips]] Moodle docs page with a few handy tips about using Git for Moodle development.

I you're looking to read/buy a book on Git I'd strongly recommend [http://progit.org/ Pro Git]. I certainly found that the most useful book I read.

[[Category:Git]]

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T02:08:28Z

Samhemelryk:

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

I would '''strongly''' suggest while learning Moodle development that you use [[User:Tim Hunt|Tim Hunt's]] fantastic [https://github.com/timhunt/moodle-local_codechecker Code Checker] plugin.<br />
You'll find information on how to use it within its README file and it will pick up many of the things that may lead to your work being rejected.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating a PULL request for the master branch==

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

===Summary===
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

===Affects Versions===
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

===Security level===
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

===Pull from repository===
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

===Pull branch===
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

===Pull Diff URL===
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

===Description===
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

===Components===
Select general from the components list, general is the only option.

===Finishing up===
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.<br />I should add that the comment isn't really required. It's just something I personally like doing.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications.
You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==The extra mile==
Now as many of you may have guessed by the time you are working on several different issues and managing several repositories the process I've described here seems VERY repetitive. And it '''IS!'''.

If you talk to any HQ developer they will tell you they deal with it in their own way, anything from scripts, to custom config files, through to virtual machine snapshots.

Personally I have a couple of bash scripts that I wrote to help me manage my workflow.

The first script I use I run after each weekly release and it does the following things:

* Moves to each repository and does the following
*# Fetches all remote changes
*# Checks whether it is safe to update my local main release branches and does that if it is safe
*# Updates all main release branches on my github account

The second script I run on every site that I have installed, it does the following

* Goes to each site I have installed and does the following
*# Overwrites the database with a stable snapshot
*# Overwrites the moodle data directory with a stable snapshot taken at the same time as the database one.
*# Upgrades the moodle site if required
*# Takes a snapshot of the database and Moodle data directory.

The third script I run whenever I start working on a new issue and it restores the stable snapshot of a sites database and moodle data directory.

These three scripts allow me to very easily ensure I am working with the latest changes and that I can easily restore to a point I know is stable and safe.

There was a fourth script I used to use but don't any more that also rebased any unmerged branches however I found it to be far to problematic and I prefer to do it myself so that I know exactly what is going on.

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.
* [[Development:Git tips]] Moodle docs page with a few handy tips about using Git for Moodle development.

I you're looking to read/buy a book on Git I'd strongly recommend [http://progit.org/ Pro Git]. I certainly found that the most useful book I read.

[[Category:Git]]

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T01:53:54Z

Samhemelryk: /* Step 2: Make changes */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

I would '''strongly''' suggest while learning Moodle development that you use [[User:Tim Hunt|Tim Hunt's]] fantastic [https://github.com/timhunt/moodle-local_codechecker Code Checker] plugin.<br />
You'll find information on how to use it within its README file and it will pick up many of the things that may lead to your work being rejected.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating a PULL request for the master branch==

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

===Summary===
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

===Affects Versions===
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

===Security level===
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

===Pull from repository===
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

===Pull branch===
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

===Pull Diff URL===
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

===Description===
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

===Components===
Select general from the components list, general is the only option.

===Finishing up===
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.<br />I should add that the comment isn't really required. It's just something I personally like doing.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications.
You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.
* [[Development:Git tips]] Moodle docs page with a few handy tips about using Git for Moodle development.

I you're looking to read/buy a book on Git I'd strongly recommend [http://progit.org/ Pro Git]. I certainly found that the most useful book I read.

[[Category:Git]]

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T01:49:16Z

Samhemelryk: /* Useful links */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating a PULL request for the master branch==

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

===Summary===
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

===Affects Versions===
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

===Security level===
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

===Pull from repository===
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

===Pull branch===
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

===Pull Diff URL===
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

===Description===
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

===Components===
Select general from the components list, general is the only option.

===Finishing up===
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.<br />I should add that the comment isn't really required. It's just something I personally like doing.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications.
You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.
* [[Development:Git tips]] Moodle docs page with a few handy tips about using Git for Moodle development.

I you're looking to read/buy a book on Git I'd strongly recommend [http://progit.org/ Pro Git]. I certainly found that the most useful book I read.

[[Category:Git]]

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T01:48:10Z

Samhemelryk: /* Useful links */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating a PULL request for the master branch==

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

===Summary===
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

===Affects Versions===
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

===Security level===
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

===Pull from repository===
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

===Pull branch===
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

===Pull Diff URL===
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

===Description===
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

===Components===
Select general from the components list, general is the only option.

===Finishing up===
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.<br />I should add that the comment isn't really required. It's just something I personally like doing.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications.
You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.
* [[Development:Git tips]] Moodle docs page with a few handy tips about using Git for Moodle development.

I you're looking to read/buy a book on Git I'd strongly recommend [http://progit.org/ Pro Git]. I certainly found that the most useful book I read.

Development:Git tips

2011-04-19T01:48:00Z

Samhemelryk: /* See Also */

{{Work in progress}}

Many developers find git a useful tool to help them with moodle development, here some tips and workflows can be shared to help others.

== Thorough Resolved Bug QA review with git ==

The power of having fast access to all of moodle commit history means we can search and checkout any point in moodle source code history which allows us to powerfully QA a bug.

Please note this workflow might not be ideal for all scenarios (for example if lots of work has been done in the same area since).

Example Workflow to QA MDL-16600:

First checkout a new branch for us to work on testing the bug in MOODLE_19_STABLE. We can delete this branch later, its less dangerous than playing any of our 'live' branches.

<pre>
$ git checkout -b QA-MDL-16600 origin/MOODLE_19_STABLE
Branch QA-MDL-16600 set up to track remote branch refs/remotes/origin/MOODLE_19_STABLE.
Switched to a new branch "QA-MDL-16600"
</pre>

Now search for any commits related to this bug fix:
<pre>
$ git log --grep='MDL-16600'
commit 1c2c8b09469ac27a3829e7267f399356a05b9810
Author: tjhunt <tjhunt>
Date: Fri Sep 26 05:49:06 2008 +0000

MDL-16600 forcedownload broken for file resources.
</pre>

In order to test that these commits fixed the bug, we will revert this commit, and then try to reproduce the reported bug:

<pre>
$ git revert -n 1c2c8b09469ac27a3829e7267f399356a05b9810
</pre>

Once we've reproduced the problem, we will reset our repository back to HEAD:
<pre>
git reset --hard HEAD
</pre>

Now if the bug is fixed, it can be closed and we can delete our branch:
<pre>
git branch -D QA-MDL-16600
</pre>

== Backporting stuff from cvshead to stable git branches ==

I (Penny) have to do this all the time and it sucks. So I made a script to make it suck less.

http://cvs.moodle.org/contrib/tools/devtools/bugstogitformatpatch?view=markup

This little perl script takes a list of bug numbers, and generates patches that you can apply with git-am

I backported Tim's roles UI work and this is how I did it.

<pre>
# make a new branch to work on
$ git checkout -b mdl19-rolesbackport origin/MOODLE_19_STABLE
</pre>

Now create some file that contains a list of bug numbers... In the case that there's only one, you can do:

<pre>
$ echo MDL-xxxxx | bugstogitformatpatch --otherargs
</pre>

Else you can do either of:

<pre>
$ cat myplan | bugstogitformatpatch --otherargs
$ bugstogitformatpatch --grepfile myplan
</pre>

This file could be a whole file with documentation and everything, but the script '''does''' expect the bug numbers to be one per-line (but accepts other junk on the same line) and start with MDL-xxxx

The script has some other options, like where to put the patches it generates, and what the revlog spec should look like (by default it will just do origin/cvshead, but you can restrict it to a different branch or even abcdefg..12345678 if you want, anything git-log can understand - see man git-rev-parse).

See --help for more information.

Now the script will run and actually much faster than I expected, for Moodle's entire history. It will spit out git-format-patch formatted patches, which you can then happily apply with git-am.

TIP: For a large feature that goes into HEAD, it may happen that someone commits bugfixes to HEAD after you've backported it, which you'll then subsequently want to apply. To get around this, I did...

<pre>
$ git tag rolesbackportedtohead origin/cvshead
</pre>

After I was done... then the next time I wanted to run the script, I just used --revlist rolesbackportedtohere..origin/cvshead to only look at patches after the last time.

== Local collaboration ==
You want to do this...

* git.moodle.org
** my organisation's git repository: aka shared repo (pulled from git.moodle.org)
*** developer 1 (local git)
*** developer 3 (local git)
*** etc.

You want to collaboratively develop Moodle stuff pushing and pulling from your local shared repository. On top of that you want the upstream repository itself to pull updates from the upstream git.moodle.org.

Some names used in the examples:

* devel-1: the first developer
* devel-2: the second developer
* shared-repo: the name of the shared repository directory
* git-moodle: the name of the unix group needed to use the shared repository

Some assuptions for the examples:

* Linux/Unix environment
* All the repositories are on the same machine (if not, only need to change git transports from git:// to git+ssh://, etc.)

Devel-1: Create local repo and configure working environment:

<pre>
cd /path/to/devel-1/dir
mkdir devel-1.git
cd devel-1.git
git init
git config --global user.name 'Devel-1 Real Name'
git config --global user.email 'devel-1@email.address'
git config --global i18n.commitEncoding 'utf8'
git config --global i18n.logOutputEncoding 'utf8'
</pre>

Get branches from git.moodle.org repo:

<pre>
git remote add -t cvshead -t MOODLE_19_STABLE -t MOODLE_18_STABLE -m cvshead moodleorg git://git.moodle.org/moodle.git
git fetch moodleorg
</pre>

Create local (work) branches:

<pre>
git branch --track cvshead-devel-1 moodleorg/cvshead
git branch --track mdl19-devel-1 moodleorg/MOODLE_19_STABLE
git branch --track mdl18-devel-1 moodleorg/MOODLE_18_STABLE
</pre>

Create local shared repo and configure it:

<pre>
cd /path/to/shared-repo/dir
mkdir shared-repo.git
cd shared-repo.git
git --bare init --shared=all
chmod g=rwxs,o=rx . # Give appropiate permissions to users in
sudo chgrp -R git-moodle . # group 'git-moodle'.
</pre>

Populate shared repo from local devel-1 repo:

<pre>
cd /path/to/devel-1/dir/devel-1.git
git remote add shared-repo /path/to/shared-repo/dir/shared-repo.git
git push shared-repo +cvshead-devel-1: +mdl19-devel-1: +mdl18-devel-1:
</pre>

Configure Devel-1 local repo branches to merge the right remote branch when pulling. We need to do this only for the first developer, as the shared repo didn't exist when we created the branches.

<pre>
cd /path/to/devel-1/dir/devel-1.git
git config branch.cvshead-devel-1.remote shared-repo
git config branch.cvshead-devel-1.merge refs/heads/cvshead-devel-1
git config branch.mdl19-devel-1.remote shared-repo
git config branch.mdl19-devel-1.merge refs/heads/mdl19-devel-1
git config branch.mdl18-devel-1.remote shared-repo
git config branch.mdl18-devel-1.merge refs/heads/mdl18-devel-1
</pre>

Create Devel-2 local repo and configure working environment:

<pre>
cd /path/to/devel-2/dir
git clone -o shared-repo /path/to/shared-repo/dir/shared-repo.git devel-2.git
cd devel-2.git
git config --global user.name 'Devel-2 Real Name'
git config --global user.email 'devel-2@email.address'
git config --global i18n.commitEncoding 'utf8'
git config --global i18n.logOutputEncoding 'utf8'
</pre>

Get branches from git.moodle.org repo:

<pre>
cd devel-2.git
git remote add -t cvshead -t MOODLE_19_STABLE -t MOODLE_18_STABLE -m cvshead moodleorg git://git.moodle.org/moodle.git
git fetch moodleorg
</pre>

Create local (work) branches from moodle.org:

<pre>
git branch --track cvshead-devel-2 moodleorg/cvshead
git branch --track mdl19-devel-2 moodleorg/MOODLE_19_STABLE
git branch --track mdl18-devel-2 moodleorg/MOODLE_18_STABLE
</pre>

From the shared-repo:

<pre>
git branch --track cvshead-devel-1 shared-repo/cvshead-devel-1
git branch --track mdl19-devel-1 shared-repo/mdl19-devel-1
git branch --track mdl18-devel-1 shared-repo/mdl18-devel-1
</pre>

Configure local branches to merge the right remote branch when pulling:

<pre>
Nothing to do :-)
</pre>

Now you can pull and push from any of the configured remote repositories (git.moodle.org and your shared local repo) by specifiying the remote repository name when using 'git pull' or 'git push'

== Consider 'gitosis' for shared development ==

If you are using git with a shared git repository, while 'ssh' access works it can be tricky to deal with permissions. 'Gitosis' allows multiple users all to access the repository using a single user on the server. Access control uses key-pairs. The article at [http://scie.nti.st/2007/11/14/hosting-git-repositories-the-easy-and-secure-way scie.nti.st] is a good introduction.

== Git "Undo" ==

Well not really! If you are about to do a git operation and you are really not sure it will save you time to simply take a copy of the entire repository first. It is likely to take orders of magnitude less time to replace the repository with the copy than to unpick a broken repository.

== Use 'git status' a lot ==

Before doing pretty much anything run 'git status' and read it. Make sure you are on the branch you think you are and that the list of changes to be committed (or not) is what you expect. It's easy to fix now than after you have done a commit (or worse still a push).

== When you forget what all your branches are ==

gitk --all

is incredibly useful for showing the relationships between branches visually.

== Know your verbose commands ==

You can get lots of information out of git, but it's not always completely obvious how. The following commands can be useful...

git branch -av

...shows all the branches (both local and remote), the last commit message and tells you (for a branch that tracks a remote) if it is forward or behind (or both!)

git branch -vv

...shows your local branches and '''which remotes they track'''. Very useful when you gave them a silly name and have forgotten what they track.

git remote -v

...lists all the remotes AND their full URLs for when you forget what they all are.

git remote show <remote_name>

...provides all the information you could ever want about a remote

== More tips please ==
(Please add your own tips here!)

==See Also==
* [[Using GIT to backup moodledata]]
* [http://moodle.org/mod/forum/discuss.php?d=119016 Moodle Development with git]
* [http://moodle.org/mod/forum/discuss.php?d=124570 Local collaboration and Git - Yeah another git question!!]
* [[User:Sam Hemelryk/My Moodle Git workflow]]

[[Category:Developer|Git tips]]
[[Category:Developer tools|Git]]
[[Category:Git]]

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T01:45:06Z

Samhemelryk: /* Rebasing after the weekly release */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating a PULL request for the master branch==

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

===Summary===
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

===Affects Versions===
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

===Security level===
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

===Pull from repository===
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

===Pull branch===
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

===Pull Diff URL===
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

===Description===
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

===Components===
Select general from the components list, general is the only option.

===Finishing up===
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.<br />I should add that the comment isn't really required. It's just something I personally like doing.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications.
You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.

I you're looking to read/buy a book on Git I'd strongly recommend [http://progit.org/ Pro Git]. I certainly found that the most useful book I read.

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T01:44:44Z

Samhemelryk: /* Rebasing after the weekly release */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating a PULL request for the master branch==

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

===Summary===
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

===Affects Versions===
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

===Security level===
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

===Pull from repository===
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

===Pull branch===
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

===Pull Diff URL===
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

===Description===
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

===Components===
Select general from the components list, general is the only option.

===Finishing up===
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.<br />I should add that the comment isn't really required. It's just something I personally like doing.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications.<br />You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.

I you're looking to read/buy a book on Git I'd strongly recommend [http://progit.org/ Pro Git]. I certainly found that the most useful book I read.

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T01:44:26Z

Samhemelryk: /* Finishing up */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating a PULL request for the master branch==

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

===Summary===
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

===Affects Versions===
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

===Security level===
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

===Pull from repository===
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

===Pull branch===
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

===Pull Diff URL===
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

===Description===
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

===Components===
Select general from the components list, general is the only option.

===Finishing up===
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.<br />I should add that the comment isn't really required. It's just something I personally like doing.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications. You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.

I you're looking to read/buy a book on Git I'd strongly recommend [http://progit.org/ Pro Git]. I certainly found that the most useful book I read.

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T01:43:06Z

Samhemelryk: /* Useful links */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating a PULL request for the master branch==

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

===Summary===
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

===Affects Versions===
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

===Security level===
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

===Pull from repository===
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

===Pull branch===
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

===Pull Diff URL===
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

===Description===
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

===Components===
Select general from the components list, general is the only option.

===Finishing up===
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications. You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.

I you're looking to read/buy a book on Git I'd strongly recommend [http://progit.org/ Pro Git]. I certainly found that the most useful book I read.

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T01:41:41Z

Samhemelryk: /* Useful links */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating a PULL request for the master branch==

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

===Summary===
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

===Affects Versions===
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

===Security level===
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

===Pull from repository===
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

===Pull branch===
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

===Pull Diff URL===
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

===Description===
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

===Components===
Select general from the components list, general is the only option.

===Finishing up===
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications. You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==Useful links==
The following are links I found useful while learning Git.

* [http://help.github.com Github help (http://help.github.com)] Provides EXCELLENT help tutorials that very clearly explain the basic through to the advanced.
* [http://cheat.errtheblog.com/s/git/ $ cheat git] This is my favourite cheat sheet, straight forward to the point, if you know the concept you'll find the answer here.
* [http://gitster.livejournal.com/28309.html Gitsters journal - Fun with FETCH_HEAD] David Mudrak pointed me at this entry which I found INCREDIBLY useful when reviewing other peoples work.

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T01:35:42Z

Samhemelryk:

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating a PULL request for the master branch==

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

===Summary===
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

===Affects Versions===
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

===Security level===
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

===Pull from repository===
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

===Pull branch===
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

===Pull Diff URL===
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

===Description===
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

===Components===
Select general from the components list, general is the only option.

===Finishing up===
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications. You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

==Useful links==
The following are links I found useful while learning Git.

* [[http://help.github.com Github help]]

User:Sam Hemelryk/My Moodle Git workflow

2011-04-19T01:33:23Z

Samhemelryk:

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating a PULL request for the master branch==

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

===Summary===
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

===Affects Versions===
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

===Security level===
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

===Pull from repository===
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

===Pull branch===
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

===Pull Diff URL===
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

===Description===
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

===Components===
Select general from the components list, general is the only option.

===Finishing up===
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

==Rebasing after the weekly release==
As many of you will be aware on Wednesday after the latest weekly has been released a comment will be added to all PULL requests that are still open.
<pre>
The main moodle.git repository has just been updated with latest weekly modifications. You may wish to rebase your PULL branches to simplify history and avoid any possible merge conflicts. This would also make integrator's life easier next week.

TIA and ciao :)
</pre>
This is a message that is bulk added as is done so as a polite request. While it's not essential for you to rebase your work it really does help the integrators as its much easier to see what is going on and greatly reduces the chance of conflicts (because you'll solve them when you rebase).

The good news is that rebasing your work is EASY!

For the following example lets assume I created the two PULL requests above on Wednesday morning and the weekly was released on Wednesday afternoon. This means that my branch doesn't have the changes that have just been released and I need to rebase them.

===Step 1: Rebasing the wip-MDL-12345-master===

The first step is to rebase my work that is based upon the master branch. So first move to the master repository.

<pre>
cd /var/www/repositories/master/moodle
</pre>

The next thing we have to do is get all of the changes from the remote repositories, this will fetch down all of the latest changes.

<pre>
git fetch --all --prune
</pre>

Now before the next step make sure that you don't have any uncommit changes, if you do finish that work, commit it, then proceed to the next step which is updating your local master.

<pre>
git checkout master
git pull
git push master github
</pre>

Now that your local master is up to date, and has you've updated you master branch at github you are ready to rebase!
At this point we want to checkout the branch we are going to rebase, in this case wip-MDL-12345-master and then we are going to rebase origin/master which is the official Moodle master branch (and the branch our branch is based upon).

<pre>
git checkout wip-MDL-12345-master
git rebase origin/master
</pre>

Once that command has completed your branch wip-MDL-12345-master will be completely up to date. Before you are done however you need to push the rebased wip-MDL-12345-master up to your github account so that its the branch the integrator sees.

<pre>
git push -f github wip-MDL-12345-master
</pre>

Now that command is just about identical to the command we used when we first pushed our branch to our github account, there is however one VERY important difference, the '''-f''' option.
The '''-f''' option tells git to force the push, this is required because when you rebase all of your commit id's will change and unless you tell git to force it will see that they have changed and not allow you to push your work.

Thats it! you've now rebased your work and the integrators will be happy again :)

===Step 2: Rebasing wip-MDL-12345-MOODLE_20_STABLE===
Now that we've rebased our work that was based upon the master branch it is time to rebase the MOODLE_20_STABLE version.
This step is just about identical to the previous step except we substitute ''master'' for ''MOODLE_20_STABLE''.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github MOODLE_20_STABLE
git checkout wip-MDL-12345-MOODLE_20_STABLE
git rebase origin/MOODLE_20_STABLE
git push -f github wip-MDL-12345-MOODLE_20_STABLE
</pre>

Done!

User:Sam Hemelryk

2011-04-18T10:07:44Z

Samhemelryk:

User:Sam Hemelryk/My Moodle Git workflow

2011-04-18T10:03:51Z

Samhemelryk: /* Before you start work each day */

This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git.

==Creating the repositories==
Ok so the very first step is to create several Moodle git repositories, one for each major branch of Moodle being worked on.

At the time of writing the major branches are MOODLE_19_STABLE, MOODLE_20_STABLE and master.

The reason for this is that that way we have a separate site for each Moodle branch that we can test on easily. Yes you will have three sites but you won't have to worry about swtiching your site when you change branches.

===Step 1: Create a directory to create the repositories within===

Personally I use Ubuntu (Linux) and I chose to create my repositories within a folder I created in /var/www. If you are using windows I would instead suggest creating C:/www/

<pre>
cd /var/www
mkdir repositories
cd repositories
</pre>

===Step 2: Create a master repository===
This is the easiest of the branches to create a repository for.

Within your repositories directory create a new directory called master and move into it:

<pre>
mkdir master
cd master
</pre>

Next we want to clone the Moodle source from the offical Moodle git repository as follows:

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

This will create a new directory called moodle within the master directory we created just before.

That new moodle directory should contain the Moodle source code as a git repository.

Now that we've got our main git repository we need to add our github account as a remote so that we can push to it later:

<pre>
cd moodle
git remote add github git@github.com:yourname/moodle.git
</pre>

This adds your moodle repository on github as a remote called github that you can push to later.

Finally before we move onto the next repository we need to create a data directory because we know we will need that:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 3: Create a MOODLE_20_STABLE repository===

The next repository we create will be for the MOODLE_20_STABLE branch.
To start with get back to the repositories directory that we created earlier and create a directory called MOODLE_20_STABLE within that.

<pre>
cd /var/www/repositories
mkdir MOODLE_20_STABLE
cd MOODLE_20_STABLE
</pre>

Now create a new clone of the main Moodle repository like we did for the master branch above.

<pre>
git clone git://git.moodle.org/moodle.git moodle
</pre>

Once we have done that move into the moodle directory.

By default the master branch is the branch that is created, however we don't want that for this repository. Instead we want the MOODLE_20_STABLE branch.

To do this we checkout local branch based upon the official MOODLE_20_STABLE branch as follows:

<pre>
git checkout -b MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

Once we have created that branch we can delete the local master branch so that we don't accidentally ever work on it.

<pre>
git branch -D master
</pre>

Then like we did for master we add our github repository as a remote:

<pre>
git remote add github git@github.com:yourname/moodle.git
</pre>

And finally create a data directory we can use when we have install the site:

<pre>
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 4: Create a MOODLE_19_STABLE repository===

This step is identical to the above step except we are using the MOODLE_19_STABLE branch instead of the MOODLE_20_STABLE branch.
The commands for this are as follows:

<pre>
cd /var/www/repositories
mkdir MOODLE_19_STABLE
cd MOODLE_19_STABLE
git clone git://git.moodle.org/moodle.git moodle
git checkout -b MOODLE_19_STABLE origin/MOODLE_19_STABLE
git branch -D master
git remote add github git@github.com:yourname/moodle.git
cd ..
mkdir data
sudo chmod -R 777 data
</pre>

===Step 5: Install the sites===
Now I can't tell you how to do this on your own machine however what I would recommend is that you create a link from your web root to the moodle directory of each branch.

If you are using linux and your webroot is /var/www/localhost you would do it as follows:

<pre>
cd /var/www/localhost/
ln -s /var/www/repositories/master/moodle master
ln -s /var/www/repositories/MOODLE_20_STABLE/moodle MOODLE_20_STABLE
ln -s /var/www/repositories/MOODLE_19_STABLE/moodle MOODLE_19_STABLE
</pre>

With that done you should be able to browse to each repository with the following URL's

<pre>
http://localhost/master/
http://localhost/MOODLE_20_STABLE/
http://localhost/MOODLE_19_STABLE/
</pre>

Once that is done you need to browse to each site and complete the installation.

Under this method your will need to ensure you set the configuration option sessioncookiepath to the URI of your site. You can either do this in the admin interfaces or add the following to your config.php file for each site.

<code php>
// For the master site
$CFG->sessioncookiepath = '/master/';
// For the MOODLE_20_STABLE site
$CFG->sessioncookiepath = '/MOODLE_20_STABLE/';
// For the MOODLE_19_STABLE site
$CFG->sessioncookiepath = '/MOODLE_19_STABLE/';
</code>

Failure to do this will mean that when you log in at one site and then visit the next you will have to log in again and your session on the first site will no longer work.

Now that you have got 3 repositories, one for each main branch, and set up a site for each you are ready to start development.

==Before you start work each day==
Before you start work each day you should update each of the repositories you have created to ensure that you are always working with up to date versions of Moodle.

You should also take this opportunity to update the repositories on your github account to ensure they are always up to date.

To start with lets update the master repository:

<pre>
cd /var/www/repositories/master/moodle
git fetch --all --prune
</pre>

This moves to the master repository and then tells git for fetch all of the changes from your remote repositories and clean up any old branches it is aware of.

Once that operation has completed you should update your master branch

<pre>
git checkout master
git pull
</pre>

Before you do that it pays to make sure you don't have any uncommit changes, if you do DON'T TRY IT. There would be a good chance you will encounter problems. Instead finish what you are working on, commit your changes and then update your master branch.

Next we will update the github repositories by running the following command:

<pre>
git push github refs/remotes/origin/master:master
</pre>

This tells git to push the master branch from origin (the offical Moodle repository) to the master branch on our github account.

Now that you've updated the master repository and your github account its time to update the MOODLE_20_STABLE and MOODLE_19_STABLE branches.

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_20_STABLE
git pull
git push github refs/remotes/origin/MOODLE_20_STABLE:MOODLE_20_STABLE
</pre>

And

<pre>
cd /var/www/repositories/MOODLE_19_STABLE/moodle
git fetch --all --prune
git checkout MOODLE_19_STABLE
git pull
git push github refs/remotes/origin/MOODLE_19_STABLE:MOODLE_19_STABLE
</pre>

==Working on a Moodle issue==

This part of the document looks at how I go about working on an MDL issue from the Moodle tracker.

At Moodle HQ we use the scrum methodology we sees us choose several issues to include in a scrum which we then work on for the period of the scrum. As a community member its more likely you will just be choosing issues that you are passionate about.

Either way once you have found an issue to work on you are ready to start.

For the purpose of this part of the document lets say I am going to work on bug MDL-12345.

==Fixing a bug on the master repository - MDL-12345==

The first step is to create a local branch to make changes on, to do this we will start our work on the master repository.

When fixing an issue I find it easiest to fix the issue on the master branch first and then move my changes to the other branches.

The VERY first thing you should do when you start working on a Moodle issue is make sure you have assigned it to yourself and then click the start progress button.

This way other users know that you are activly working on the bug and no one from HQ will steal it from you.

===Step 1: Creating a local branch===

So first get to the master repository:

<pre>
cd /var/www/repositories/master/moodle
</pre>

Once there we create a new branch as follows:

<pre>
git checkout -b wip-MDL-12345-master origin/master
</pre>

This command checks out a new branch called wip-MDL-12345-master that is based upon origin/master.

origin/master is of course the master branch on the official Moodle repository (git.moodle.org/moodle.git).

The name of the branch is also very important. It is essentially telling us three things.

; wip : This stands for work in progress, it helps people see that you are currently working on this branch and that they shouldn't base there work on it because it will likely change.
; MDL-12345 : This is of course the Moodle bug number. It helps people quickly identify what you are working on.
; master : This is the branch we are making changes on. It helps people quickly understand where the changes are being made.

You can optionally add more to the end of the branch name such as a key word that identifies the area or a date at which you started work e.g.

* wip-MDL-12345-master-navigation-changes
* wip-MDL-12345-master-20110418

That is up to you, personally I'm not a fan of it, however the rest is all required to help integrate your work.

Either way now you have a branch, mine is called wip-MDL-12345-master.

===Step 2: Make changes===

Now that you have created you branch you are ready to make changes.

I'll let you make whatever changes you are need, once you have made changes move onto the next step.

Before you do move on however make sure that your code meets the high quality of code Moodle requires.

You can find information about that on the moodle docs here: https://docs.moodle.org/en/Development:Coding_style

The following are common mistakes:

* Incorrect white space
** Tabs instead of spaces
** Extra spaces at the end of lines
** Multiple new lines
** Forgetting to put spaces between function arguments
* Incorrect commit messages (read on to find out about writing a good commit message)
* Incorrect variable or function names

Making these sort of mistakes can lead to your code being rejected despite it working correctly.

Or course it will be reviewed in regards to security, usability and the other important factors of code development.

===Step 3: Commit your changes===

Now that you have made your changes you are getting ready to commit them.

The first thing to do is check your changes. To do this run the following command:

<pre>
git status
</pre>

You should see all of the files you have changes highlighted in red.

Next you need to stage all of the files you want to commit.

To do this you add the files to the stage using the following command.

<pre>
git add lib/modifiedfile.php
git add lib/newfile.php
git add theme/base/style/core.css
</pre>

Why not just commit all changes. Many of the git guides you read will tell you above git commit -a which commits all of the changes you have made.

We've hardly being using git here at Moodle and already I've seen several people accidentally commit changes that they didn't mean to.

Staging files like this ENSURES you only commit things you intend to.

Now that you have staged your changes/new files you are ready to commit. The following command commits your changes:

<pre>
git commit -m "MDL-12345 enrol - Fixed up a couple of enrolment bugs"
</pre>

This command commits your changes with the commit message "MDL-12345 enrol - Fixed up a couple of enrolment bugs".
It's very important to Moodle that you format your commit messages like this.
They consist of three parts:

# The MDL bug number in this case MDL-12345
# The area you made changes to in this case enrol
# A short description of what you did, in this case I fixed a couple of enrolment bugs.

When you commit your message you will see something like the following:

<pre>
[master 19a484e] changes
1 files changed, 16 insertions(+), 18 deletions(-)
</pre>

There is one thing here you need to note down for later, that is the number that appears within the square brackets after the branch name, in my case it is 19a484e. This is the commit id of the commit I just made.

===Step 4: Pushing your changes to your github account===

Now that you have made changes to your local branch you should push it to your github account so that it can be reviewed and hopefully integrated into Moodle.

Doing this is very simple just run the following command:

<pre>
git push github wip-MDL-12345-master
</pre>

Here we are telling git to push the branch wip-MDL-12345-master to the remote called github which we added when setting up our git repositories.
And just like that you've made a branch that contains your work and pushed it to github ready to get it reviewed.

==Moving your changes to another branch==
Now that you have made changes to the master branch you need to decide whether it is appropriate make those changes on any of the other branches.
Most likely if you are fixing a bug you will need to make the changes on the MOODLE_20_STABLE branch as well, and perhaps the MOODLE_19_STABLE branch if it is a security bug.

Lets assume for MDL-12345 that I fixed earlier that it should be ported to MOODLE_20_STABLE as well.

===Step 1: Creating a local MOODLE_20_STABLE branch===

To start with I need to move to the MOODLE_20_STABLE repository as follows:

<pre>
cd /var/www/repositories/MOODLE_20_STABLE/moodle
</pre>

Once there I need to create a new branch based upon the MOODLE_20_STABLE branch that is going to contain my changes.

<pre>
git checkout -b wip-MDL-12345-MOODLE_20_STABLE origin/MOODLE_20_STABLE
</pre>

This is very similar to the branch we created for the changes to the master branch except that I have subsituted MOODLE_20_STABLE in place of master. This is because the new branch we are creating is based upon the MOODLE_20_STABLE branch on the offical Moodle git repository and contains changes for that branch.

===Step 2: Cherry-picking my changes===
Once we have a branch for our changes I am ready to make them again. There is however with git an easy way to do this, cherry-picking.

Cherry-picking is the process of copying a single commit from one branch to another. In this case I want to cherry pick the commit I made earlier onto the branch I've just created.

However before I can do this I need to fetch the changes I made from the github repository. I need to do this because I made that changes of a totally separate local repository remember.

So to update my repository with the latest changes I run the following command.

<pre>
git fetch --all --prune
</pre>

This command tells git to look at each remote and get any new changes (it also removes any branches that have been deleted).
Once it has completed you will be ready to cherry pick the commit. To do so you use the following command but replace my commit is with yours.

<pre>
git cherry-pick 19a484e
</pre>

Providing there are no conflicts your branch will now contain a copy of the changes you made to the master branch.
If there are conficts that you will need to resolve them and commit your changes however you can search for another tutorial about how to do that,

Now I know at this point that there will be some of you who are saying 'Whoops I forgot what my commit id was!'. If this is you don't worry, its pretty easy to find it providing you used a proper commit message like I described above.
Simply run the following command:

<pre>
git log --oneline origin/master..github/wip-MDL-12345-master
</pre>

This command shows you all of the commits that are in the wip-MDL-12345-master at your github account but are not in the master branch at the offical Moodle repository.
You can then cherry-pick the commits shown there (the commit ID's should be highlighted in yellow).

Once you have cherry-picked your commits its time to check that everything worked, run the command:

<pre>
git status
</pre>

You should see something like the following:

<pre>
# On branch wip-MDL-12345-MOODLE_20_STABLE
# Your branch is ahead of 'origin/MOODLE_20_STABLE' by 1 commit.
#
nothing to commit (working directory clean)
</pre>

This is very handy as it tells you that your branch is ahead of the offical MOODLE_20_STABLE branch by one commit.
You can also check that your commit contains the changes you think by running the following command:

<pre>
git diff origin/MOODLE_20_STABLE
</pre>

This command shows you all of the changes you have made as a diff.

Now that you know that your commit is there you and that it is correct it is time to push it to your github account.

<pre>
git push github wip-MDL-12345-MOODLE_20_STABLE
</pre>

And thats it.

You github account should now have two branches on it:

; wip-MDL-12345-master : This branch is the changes you have made for the master branch
; wip-MDL-12345-MOODLE_20_STABLE : This branch is those same changes but for the MOODLE_20_STABLE branch

Now you are ready to create PULL requests so that your work gets reviewed and hopefully integrated.

==Creating a PULL request for the master branch==

So you have successfully fixed the bug MDL-12345, you have created two branches one for master and one for MOODLE_20_STABLE. It is time to create a PULL request for each of these branches.

First lets create a PULL request for the master branch:

# Browse to tracker.moodle.org/browse/MDL-12345
# When the page loads log in if you haven't already.
# Click on the button in the top right labelled `Create issue`
# Change Project to `Pull Requests`
# Change Issue type to `Pull Request`
# Click create

This takes you to a screen where you can enter the details for the PULL request.

You should fill it out in the following way:

===Summary===
This is the summary for the PULL request, you should copy and paste the summary from the MDL issue here.
For MDL-12345 the summary is `alphabetization of UI different on left and right sides` so that's what I will use.

===Affects Versions===
This is the version that your branch is changing, in the case of this PULL request I will select `master`.

===Security level===
If the issue you are working on is a security issue you should set this to the same level that the issue is set to. If its not a security issue or you don't know just leave it as none.

===Pull from repository===
This is the repository that the branch is at, for you this will be your github accont. If you head to http://github.com/yourname/moodle you will see a box that has three options SSH, HTTP, and Git read only, click Git Read Only and then copy the contents of the text box into the repositry field of the PULL request.
For me that is git://github.com/yourname/moodle.git

===Pull branch===
This is the name of the branch that contains your changes. For me that is wip-MDL-12345-master.

===Pull Diff URL===
This is the URL to a page that shows the changes that you've made on your branch. Github is nice in that it has a pretty interface for that. To get to the interface follow these steps:

# Browse to https://github.com/youraccount/moodle
# Click `Switch Branches` and then click on the branch you changes are based upon, in my case master.
# Click the button labelled `Branch List`
# Locate your branch in the list and click the `Compare button` for me this was the compare button to the right of wip-MDL-12345-master.
# Copy the URL in your browse and paste it into the Pull Diff URL of the PULL request.

For me this URL was: https://github.com/yourname/moodle/compare/master...wip-MDL-23532-master
For the MOODLE_20_STABLE branch this would be: https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE

===Description===
The description should contain several bits of important information:

# A short description of what your patch does
# Notes about that changes you've made that might help the integrator understand what you did when he/she is reviewing it.
# Testing instructions that guide the testers through testing your changes.

===Components===
Select general from the components list, general is the only option.

===Finishing up===
Once you have filled in the fields as above click `Create`. This should create you PULL request and then take you to view it.

Its important to remember that there is still one thing you need to do and that is link to the original issue.
While you are still logged in click the `More Actions` button and select `Link issue`, in the dialoug that pops up change the `This issue` field to `will help resolve`, type MDL-12345 into the issues field, and then type `Linking to MDL-12345` into the comments box. Once you've done that simple click Link.

Time to create the PULL request for the other branches.

==Creating the PULL request for MOODLE_20_STABLE==
Once you've created the PULL request for the master branch it is time to create the PULL request for the MOODLE_20_STABLE branch.
This is as easy as can be, click Create Issue in the top right, select PULL project and choose Pull Request and then click create.
On the next screen enter the following details:

; Summary : Copy the summary from the previous PULL Request
; Affects Versions : Select MOODLE_20_STABLE
; Security level : Same as the MDL
; Pull from repository : Copy from the previous PULL request
; Pull Branch : wip-MDL-12345-MOODLE_20_STABLE
; Pull Diff URL : https://github.com/yourname/moodle/compare/MOODLE_20_STABLE...wip-MDL-23532-MOODLE_20_STABLE
; Description : Copy from the previous PULL request
; Component : general

Then click create to create the PULL request.

Once the PULL request has been create don't forget to link to the MDL issue like we did for the previous PULL request.

User:Sam Hemelryk/My Moodle Git workflow

2011-04-18T09:56:03Z

Samhemelryk:

User:Sam Hemelryk/My Moodle Git workflow

2011-04-18T09:54:25Z

Samhemelryk: Created page with "This document is a sort of tutorial/inspection of my personal development workflow when working on Moodle with Git. ==Creating the repositories== Ok so the very first step is to..."

Development:Themes 2.0 adding upgrade code

2011-04-11T07:23:30Z

Samhemelryk: /* Step 2: install.php */

As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.

==Why?==
As part of the Moodle 2 revamp theme's have been given the same abilities as many of the other plugin types within Moodle. They are now able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things.

Unfortunately this change has its positives and negatives, on the positive you can now really get some cool stuff happening within a theme, the downside is just like any other plugin you need to think about those who are already using your theme when you make changes.

If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme.

==Step 1: version.php==
For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new.

The version.php file is a requirement for many plugin types, however for theme's it is optional. The idea is that it contains just two or three lines of code that tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''.

The following is an example of what a version.php file for a theme looks like.

<code php>
<?php

/**
* This is the version.php file for my theme.
*/
defined('MOODLE_INTERNAL') || die;

$plugin->version = 2011032900;
$plugin->component = 'theme_mythemename';
$plugin->requires = 2010122500;
$plugin->maturity = MATURITY_STABLE;
</code>

The first thing to notice here is that we are setting properties of an object called $plugin, this object will be used to describe our theme.
We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put them in as well.
===The version property===
The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle.

The format is YYYYMMDDXX :
# YYYY is the four digit year, e.g. 2011
# MM is the month with preceding 0 if required, e.g. 03
# DD is the day with preceding 0 is required, e.g. 28
# XX is an incrementing value starting at 00, you can increment this if you add several upgrade code blocks on the same day.

As a hint its easiest just to set the version property to today's date when adding upgrade code, or releasing a version of your theme that introduces something new such as a database table, or config setting.

===The component property===
The component is used to describe the plugin and its type. In our case we are working with themes and the theme name I have used in my example is mythemename, therefore the component is theme_mythemename.

When installing or upgrading a plugin Moodle checks the component and uses it to make sure that the plugin has been installed in the correct location. This is particularly helpful for the end user as it prevents nasty accidents where they accidentally put a plugin in the wrong place.

If you are working on other types of plugins the component of course will differ, its best to refer to the docs for those plugin types to find out what you would have to use there.

===The requires property===
The requires property sets the version of Moodle that is required by this plugin. This is particularly handy if your plugin makes use of a feature that was introduced in a specific version of Moodle, or if your plugin relies on a bug fix that was introduced in a specific version.

You can find the current Moodle version by looking at main Moodle version.php file. In the example above I have set my theme to require Moodle 2.0.1 by setting the requires property to Moodle's version number when that was released. If you are trying to find out a specific version number you can do so by heading to https://github.com/moodle/moodle, changing the tag drop down to the version you desire, then inspecting the version.php file at the bottom of the files list. You should see $version = XXXXXXXXXX;.

===The maturity property===
This is a property that is expected to be fully supported in Moodle 2.1. It informs Moodle about the state of the code and can be one of the following values:
; MATURITY_STABLE : Use this when the theme is stable and works well.
; MATURITY_RC : This marks the theme as a release candidate, users can expect the theme to contain one or two bugs but be largely stable and usable.
; MATURITY_BETA : This marks the theme as a beta release, users can expect the theme to contain several bugs and for it to be likely to change still.
; MATURITY_ALPHA : This marks the theme as an alpha release, this is the first release of a new theme and users will expect to find a lot still needs to be done.

==Step 2: install.php==
If as part of this upgrade you are adding a version.php file to your theme then you will need to add your upgrade code to install.php rather than upgrade.php.

The reason for this is because Moodle processes install.php the first time that a version number is used rather than upgrade.php.

The install.php file should contain a single function that needs to be named following a strict naming scheme and it should be located in a directory called db located within your theme's directory, for example '''moodle/theme/mythemename/db/install.php'''.

For this example I have called my theme ''mythemename'' so the function will be as follows:
<code php>

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_install() {
// We'll look at what is in here shortly.

return true;
}
</code>

This special function is called when a theme is first installed (if it has a version.php file and it has been newly added to your Moodle site) or the first time that the theme has a version.php file if you are developing or upgrading a theme.

The install function can perform any upgrade routines you require. For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

<code php>

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_install() {
$currentsetting = get_config('theme_mythemename');

// Create a new config called settinga and give it settingone's value.
set_config('settinga', $currentsetting->settingone, 'theme_mythemename');
// Remove settingone
unset_config('settingone', 'theme_mythemename');

// Create a new config called settingb and give it settingtwo's value.
set_config('settingb', $currentsetting->settingtwo, 'theme_mythemename');
// Remove settingtwo
unset_config('settingtwo', 'theme_mythemename');

return true;
}
</code>

Looking at this code it does the following things:
# The install code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value.
# It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo.
# It returns true so that Moodle knows the installation was successful.

And thats it, there's no need to add an upgrade.php file at this point.

==Step 3: upgrade.php==
The upgrade.php script allows you to write upgrade code for subsequent upgrade requirements for your theme. If your theme already has a version.php then you should bump the version number there and add your upgrade code here.

This is the main upgrade file. It should be located in a directory called ''db'' located within your theme's directory, for example '''moodle/theme/mythemename/db/upgrade.php'''.

The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows:
<code php>
<?php

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_upgrade($oldversion) {
// We'll look at what is in here shortly.

return true;
}
</code>

This special function gets called when ever the admin is upgrading the site and gives our theme the opportunity to run any upgrade code it requires.

Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation.

For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

<code php>
<?php

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_upgrade($oldversion) {

if ($oldversion < 2011032900) {
$currentsetting = get_config('theme_mythemename');

// Create a new config called settinga and give it settingone's value.
set_config('settinga', $currentsetting->settingone, 'theme_mythemename');
// Remove settingone
unset_config('settingone', 'theme_mythemename');

// Create a new config called settingb and give it settingtwo's value.
set_config('settingb', $currentsetting->settingtwo, 'theme_mythemename');
// Remove settingtwo
unset_config('settingtwo', 'theme_mythemename');

// Upgrade the version that Moodle knows is installed so that this upgrade
// isn't run again.
upgrade_plugin_savepoint(true, 2011032900, 'theme', 'mythemename');
}

return true;
}
</code>

Looking at this code it does the following things:
# It compares and the '''$oldversion''' to the version we set (2011032900) and our version is newer it runs the upgrade code.
# The upgrade code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value.
# It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo.
# It updates the version Moodle knows is installed by calling ''upgrade_plugin_savepoint''
# Finally the function returns true so that the rest of the upgrade continues.

==Done==
Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file.

==More information==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 adding a settings page]]

Development:Themes 2.0 adding upgrade code

2011-04-11T07:21:56Z

Samhemelryk: /* Step 2: install.php */

As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.

==Why?==
As part of the Moodle 2 revamp theme's have been given the same abilities as many of the other plugin types within Moodle. They are now able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things.

Unfortunately this change has its positives and negatives, on the positive you can now really get some cool stuff happening within a theme, the downside is just like any other plugin you need to think about those who are already using your theme when you make changes.

If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme.

==Step 1: version.php==
For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new.

The version.php file is a requirement for many plugin types, however for theme's it is optional. The idea is that it contains just two or three lines of code that tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''.

The following is an example of what a version.php file for a theme looks like.

<code php>
<?php

/**
* This is the version.php file for my theme.
*/
defined('MOODLE_INTERNAL') || die;

$plugin->version = 2011032900;
$plugin->component = 'theme_mythemename';
$plugin->requires = 2010122500;
$plugin->maturity = MATURITY_STABLE;
</code>

The first thing to notice here is that we are setting properties of an object called $plugin, this object will be used to describe our theme.
We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put them in as well.
===The version property===
The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle.

The format is YYYYMMDDXX :
# YYYY is the four digit year, e.g. 2011
# MM is the month with preceding 0 if required, e.g. 03
# DD is the day with preceding 0 is required, e.g. 28
# XX is an incrementing value starting at 00, you can increment this if you add several upgrade code blocks on the same day.

As a hint its easiest just to set the version property to today's date when adding upgrade code, or releasing a version of your theme that introduces something new such as a database table, or config setting.

===The component property===
The component is used to describe the plugin and its type. In our case we are working with themes and the theme name I have used in my example is mythemename, therefore the component is theme_mythemename.

When installing or upgrading a plugin Moodle checks the component and uses it to make sure that the plugin has been installed in the correct location. This is particularly helpful for the end user as it prevents nasty accidents where they accidentally put a plugin in the wrong place.

If you are working on other types of plugins the component of course will differ, its best to refer to the docs for those plugin types to find out what you would have to use there.

===The requires property===
The requires property sets the version of Moodle that is required by this plugin. This is particularly handy if your plugin makes use of a feature that was introduced in a specific version of Moodle, or if your plugin relies on a bug fix that was introduced in a specific version.

You can find the current Moodle version by looking at main Moodle version.php file. In the example above I have set my theme to require Moodle 2.0.1 by setting the requires property to Moodle's version number when that was released. If you are trying to find out a specific version number you can do so by heading to https://github.com/moodle/moodle, changing the tag drop down to the version you desire, then inspecting the version.php file at the bottom of the files list. You should see $version = XXXXXXXXXX;.

===The maturity property===
This is a property that is expected to be fully supported in Moodle 2.1. It informs Moodle about the state of the code and can be one of the following values:
; MATURITY_STABLE : Use this when the theme is stable and works well.
; MATURITY_RC : This marks the theme as a release candidate, users can expect the theme to contain one or two bugs but be largely stable and usable.
; MATURITY_BETA : This marks the theme as a beta release, users can expect the theme to contain several bugs and for it to be likely to change still.
; MATURITY_ALPHA : This marks the theme as an alpha release, this is the first release of a new theme and users will expect to find a lot still needs to be done.

==Step 2: install.php==
If as part of this upgrade you are adding a version.php file to your theme then you will need to add your upgrade code to install.php rather than upgrade.php.

The reason for this is because Moodle processes install.php the first time that a version number is used rather than upgrade.php.

The install.php file should contain a single function that needs to be named following a strict naming scheme and it should be located in a directory called db located within your theme's directory, for example moodle/theme/mythemename/db/install.php.

For this example I have called my theme ''mythemename'' so the function will be as follows:
<code php>

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_install() {
// We'll look at what is in here shortly.

return true;
}
</code>

This special function is called when a theme is first installed (if it has a version.php file and it has been newly added to your Moodle site) or the first time that the theme has a version.php file if you are developing or upgrading a theme.

The install function can perform any upgrade routines you require. For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

<code php>

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_install() {
$currentsetting = get_config('theme_mythemename');

// Create a new config called settinga and give it settingone's value.
set_config('settinga', $currentsetting->settingone, 'theme_mythemename');
// Remove settingone
unset_config('settingone', 'theme_mythemename');

// Create a new config called settingb and give it settingtwo's value.
set_config('settingb', $currentsetting->settingtwo, 'theme_mythemename');
// Remove settingtwo
unset_config('settingtwo', 'theme_mythemename');

return true;
}
</code>

Looking at this code it does the following things:
# The install code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value.
# It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo.
# It returns true so that Moodle knows the installation was successful.

And thats it, there's no need to add an upgrade.php file at this point.

==Step 3: upgrade.php==
The upgrade.php script allows you to write upgrade code for subsequent upgrade requirements for your theme. If your theme already has a version.php then you should bump the version number there and add your upgrade code here.

This is the main upgrade file. It should be located in a directory called ''db'' located within your theme's directory, for example '''moodle/theme/mythemename/db/upgrade.php'''.

The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows:
<code php>
<?php

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_upgrade($oldversion) {
// We'll look at what is in here shortly.

return true;
}
</code>

This special function gets called when ever the admin is upgrading the site and gives our theme the opportunity to run any upgrade code it requires.

Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation.

For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

<code php>
<?php

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_upgrade($oldversion) {

if ($oldversion < 2011032900) {
$currentsetting = get_config('theme_mythemename');

// Create a new config called settinga and give it settingone's value.
set_config('settinga', $currentsetting->settingone, 'theme_mythemename');
// Remove settingone
unset_config('settingone', 'theme_mythemename');

// Create a new config called settingb and give it settingtwo's value.
set_config('settingb', $currentsetting->settingtwo, 'theme_mythemename');
// Remove settingtwo
unset_config('settingtwo', 'theme_mythemename');

// Upgrade the version that Moodle knows is installed so that this upgrade
// isn't run again.
upgrade_plugin_savepoint(true, 2011032900, 'theme', 'mythemename');
}

return true;
}
</code>

Looking at this code it does the following things:
# It compares and the '''$oldversion''' to the version we set (2011032900) and our version is newer it runs the upgrade code.
# The upgrade code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value.
# It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo.
# It updates the version Moodle knows is installed by calling ''upgrade_plugin_savepoint''
# Finally the function returns true so that the rest of the upgrade continues.

==Done==
Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file.

==More information==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 adding a settings page]]

Development:Themes 2.0 adding upgrade code

2011-04-11T07:06:44Z

Samhemelryk:

As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.

==Why?==
As part of the Moodle 2 revamp theme's have been given the same abilities as many of the other plugin types within Moodle. They are now able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things.

Unfortunately this change has its positives and negatives, on the positive you can now really get some cool stuff happening within a theme, the downside is just like any other plugin you need to think about those who are already using your theme when you make changes.

If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme.

==Step 1: version.php==
For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new.

The version.php file is a requirement for many plugin types, however for theme's it is optional. The idea is that it contains just two or three lines of code that tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''.

The following is an example of what a version.php file for a theme looks like.

<code php>
<?php

/**
* This is the version.php file for my theme.
*/
defined('MOODLE_INTERNAL') || die;

$plugin->version = 2011032900;
$plugin->component = 'theme_mythemename';
$plugin->requires = 2010122500;
$plugin->maturity = MATURITY_STABLE;
</code>

The first thing to notice here is that we are setting properties of an object called $plugin, this object will be used to describe our theme.
We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put them in as well.
===The version property===
The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle.

The format is YYYYMMDDXX :
# YYYY is the four digit year, e.g. 2011
# MM is the month with preceding 0 if required, e.g. 03
# DD is the day with preceding 0 is required, e.g. 28
# XX is an incrementing value starting at 00, you can increment this if you add several upgrade code blocks on the same day.

As a hint its easiest just to set the version property to today's date when adding upgrade code, or releasing a version of your theme that introduces something new such as a database table, or config setting.

===The component property===
The component is used to describe the plugin and its type. In our case we are working with themes and the theme name I have used in my example is mythemename, therefore the component is theme_mythemename.

When installing or upgrading a plugin Moodle checks the component and uses it to make sure that the plugin has been installed in the correct location. This is particularly helpful for the end user as it prevents nasty accidents where they accidentally put a plugin in the wrong place.

If you are working on other types of plugins the component of course will differ, its best to refer to the docs for those plugin types to find out what you would have to use there.

===The requires property===
The requires property sets the version of Moodle that is required by this plugin. This is particularly handy if your plugin makes use of a feature that was introduced in a specific version of Moodle, or if your plugin relies on a bug fix that was introduced in a specific version.

You can find the current Moodle version by looking at main Moodle version.php file. In the example above I have set my theme to require Moodle 2.0.1 by setting the requires property to Moodle's version number when that was released. If you are trying to find out a specific version number you can do so by heading to https://github.com/moodle/moodle, changing the tag drop down to the version you desire, then inspecting the version.php file at the bottom of the files list. You should see $version = XXXXXXXXXX;.

===The maturity property===
This is a property that is expected to be fully supported in Moodle 2.1. It informs Moodle about the state of the code and can be one of the following values:
; MATURITY_STABLE : Use this when the theme is stable and works well.
; MATURITY_RC : This marks the theme as a release candidate, users can expect the theme to contain one or two bugs but be largely stable and usable.
; MATURITY_BETA : This marks the theme as a beta release, users can expect the theme to contain several bugs and for it to be likely to change still.
; MATURITY_ALPHA : This marks the theme as an alpha release, this is the first release of a new theme and users will expect to find a lot still needs to be done.

==Step 2: install.php==
If as part of this upgrade you are adding a version.php file to your theme then you will need to add your upgrade code to install.php rather than upgrade.php.

The reason for this is because Moodle processes install.php the first time that a version number is used rather than upgrade.php.

The install.php file should contain a single function that needs to be named following a strict naming scheme.
For this example I have called my theme ''mythemename'' so the function will be as follows:
<code php>

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_install() {
// We'll look at what is in here shortly.

return true;
}
</code>

This special function is called when a theme is first installed (if it has a version.php file and it has been newly added to your Moodle site) or the first time that the theme has a version.php file if you are developing or upgrading a theme.

The install function can perform any upgrade routines you require. For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

<code php>

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_install() {
$currentsetting = get_config('theme_mythemename');

// Create a new config called settinga and give it settingone's value.
set_config('settinga', $currentsetting->settingone, 'theme_mythemename');
// Remove settingone
unset_config('settingone', 'theme_mythemename');

// Create a new config called settingb and give it settingtwo's value.
set_config('settingb', $currentsetting->settingtwo, 'theme_mythemename');
// Remove settingtwo
unset_config('settingtwo', 'theme_mythemename');

return true;
}
</code>

Looking at this code it does the following things:
# The install code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value.
# It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo.
# It returns true so that Moodle knows the installation was successful.

And thats it, there's no need to add an upgrade.php file at this point.

==Step 3: upgrade.php==
The upgrade.php script allows you to write upgrade code for subsequent upgrade requirements for your theme. If your theme already has a version.php then you should bump the version number there and add your upgrade code here.

This is the main upgrade file. It should be located in a directory called ''db'' located within your theme's directory, for example '''moodle/theme/mythemename/db/upgrade.php'''.

The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows:
<code php>
<?php

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_upgrade($oldversion) {
// We'll look at what is in here shortly.

return true;
}
</code>

This special function gets called when ever the admin is upgrading the site and gives our theme the opportunity to run any upgrade code it requires.

Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation.

For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

<code php>
<?php

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_upgrade($oldversion) {

if ($oldversion < 2011032900) {
$currentsetting = get_config('theme_mythemename');

// Create a new config called settinga and give it settingone's value.
set_config('settinga', $currentsetting->settingone, 'theme_mythemename');
// Remove settingone
unset_config('settingone', 'theme_mythemename');

// Create a new config called settingb and give it settingtwo's value.
set_config('settingb', $currentsetting->settingtwo, 'theme_mythemename');
// Remove settingtwo
unset_config('settingtwo', 'theme_mythemename');

// Upgrade the version that Moodle knows is installed so that this upgrade
// isn't run again.
upgrade_plugin_savepoint(true, 2011032900, 'theme', 'mythemename');
}

return true;
}
</code>

Looking at this code it does the following things:
# It compares and the '''$oldversion''' to the version we set (2011032900) and our version is newer it runs the upgrade code.
# The upgrade code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value.
# It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo.
# It updates the version Moodle knows is installed by calling ''upgrade_plugin_savepoint''
# Finally the function returns true so that the rest of the upgrade continues.

==Done==
Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file.

==More information==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 adding a settings page]]

Development:Themes 2.0 creating your first theme

2011-03-29T06:15:02Z

Samhemelryk:

{{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.

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.

==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-03-29T06:13:24Z

Samhemelryk: Better coding standard

{{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>
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]]

Development:Themes 2.0 adding a settings page

2011-03-29T02:57:50Z

Samhemelryk: /* More information */

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

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

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

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

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

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

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

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

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

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

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

Well lets get into it....

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Alright.

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

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

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

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

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

<code php>
<?php

/**
* Settings for the demystified theme
*/

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

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

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

====Background colour====

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

/**
* Settings for the demystified theme
*/

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

return $css;
}
</code>

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

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

This of course is the function declaration.

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

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

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

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

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

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

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

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

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

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

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

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

First up demystified_set_backgroundcolor.

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

Ok so what is happening here?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

===Finishing it all off===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

This is probably the easiest setting to implement.

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

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

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

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

<code php>

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

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

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

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

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

So in this tutorial we have achieved the following:

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

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

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

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

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

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

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

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

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

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

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

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

==Common pitfalls and useful notes==

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

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

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

Development:Themes 2.0

2011-03-29T02:52:37Z

Samhemelryk: /* See also */

{{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 echo $PAGE->bodyid ?>" class="<?php echo $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 echo $PAGE->bodyid; ?>" class="<?php echo $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>
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]]

Development:Themes 2.0 adding upgrade code

2011-03-29T02:52:08Z

Samhemelryk:

As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.

==Why?==
As part of the Moodle 2 revamp theme's have been given the same abilities as many of the other plugin types within Moodle. They are now able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things.

Unfortunately this change has its positives and negatives, on the positive you can now really get some cool stuff happening within a theme, the downside is just like any other plugin you need to think about those who are already using your theme when you make changes.

If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme.

==Step 1: version.php==
For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new.

The version.php file is a requirement for many plugin types, however for theme's it is optional. The idea is that it contains just two or three lines of code that the tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''.

The following is an example of what a version.php file for a theme looks like.

<code php>
<?php

/**
* This is the version.php file for my theme.
*/
$plugin->version = 2011032900;
$plugin->component = 'theme_mythemename';
$plugin->requires = 2010122500;
$plugin->maturity = MATURITY_STABLE;
</code>

The first thing to notice here is that we are setting properties of an object called $plugin, this object will be used to describe our theme.
We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put the in as well.
===The version property===
The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle.

The format is YYYYMMDDXX :
# YYYY is the four digit year, e.g. 2011
# MM is the month with preceding 0 if required, e.g. 03
# DD is the day with preceding 0 is required, e.g. 28
# XX is an incrementing value starting at 00, you can increment this if you add several upgrade code blocks on the same day.

As a hint its easiest just to set the version property to today's date when adding upgrade code, or releasing a version of your theme that introduces something new such as a database table, or config setting.

===The component property===
The component is used to describe the plugin and its type. In our case we are working with themes and the theme name I have used in my example is mythemename, therefore the component is theme_mythemename.

When installing or upgrading a plugin Moodle checks the component and uses it to make sure that the plugin has been installed in the correct location. This is particularly helpful for the end user as it prevents nasty accidents where they accidentally put a plugin in the wrong place.

If you are working on other types of plugins the component of course will differ, its best to refer to the docs for those plugin types to find out what you would have to use there.

===The requires property===
The requires property sets the version of Moodle that is required by this plugin. This is particularly handy if your plugin makes use of a feature that was introduced in a specific version of Moodle, or if your plugin relies on a bug fix that was introduced in a specific version.

You can find the current Moodle version by looking at main Moodle version.php file. In the example above I have set my theme to require Moodle 2.0.1 by setting the requires property to Moodle's version number when that was released. If you are trying to find out a specific version number you can do so by heading to https://github.com/moodle/moodle, changing the tag drop down to the version you desire, then inspecting the version.php file at the bottom of the files list. You should see $version = XXXXXXXXXX;.

===The maturity property===
This is a property that is expected to be fully supported in Moodle 2.1. It informs Moodle about the state of the code and can be one of the following values:
; MATURITY_STABLE : Use this when the theme is stable and works well.
; MATURITY_RC : This marks the theme as a release candidate, users can expect the theme to contain one or two bugs but be largely stable and usable.
; MATURITY_BETA : This marks the theme as a beta release, users can expect the theme to contain several bugs and for it to be likely to change still.
; MATURITY_ALPHA : This marks the theme as an alpha release, this is the first release of a new theme and users will expect to find a lot still needs to be done.

==Step 2: upgrade.php==
This is the main upgrade file. It should be located in a directory called ''db'' located within your theme's directory, for example '''moodle/theme/mythemename/db/upgrade.php'''.

The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows:
<code php>
<?php

function xmldb_mythemename_anomaly_upgrade($oldversion) {
// We'll look at what is in here shortly.

return true;
}
</code>

This special function gets called when ever the admin is upgrading the site and gives our theme the opportunity to run any upgrade code it requires.

Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation.

For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

<code php>
<?php

function xmldb_theme_mythemename_upgrade($oldversion) {

if ($oldversion < 2011032900) {
$currentsetting = get_config('theme_mythemename');

// Create a new config called settinga and give it settingone's value.
set_config('settinga', $currentsetting->settingone, 'theme_mythemename');
// Remove settingone
unset_config('settingone', 'theme_mythemename');

// Create a new config called settingb and give it settingtwo's value.
set_config('settingb', $currentsetting->settingtwo, 'theme_mythemename');
// Remove settingtwo
unset_config('settingtwo', 'theme_mythemename');

// Upgrade the version that Moodle knows is installed so that this upgrade
// isn't run again.
upgrade_plugin_savepoint(true, 2011032900, 'theme', 'mythemename');
}

return true;
}
</code>

Looking at this code it does the following things:
# It compares and the '''$oldversion''' to the version we set (2011032900) and our version is newer it runs the upgrade code.
# The upgrade code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value.
# It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo.
# It updates the version Moodle knows is installed by calling ''upgrade_plugin_savepoint''
# Finally the function returns true so that the rest of the upgrade continues.

==Done==
Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file.

==More information==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 adding a settings page]]

Development:Themes 2.0 adding upgrade code

2011-03-29T02:31:31Z

Samhemelryk: /* Step 1: version.php */

Development:Themes 2.0 adding upgrade code

2011-03-29T02:04:28Z

Samhemelryk: New page: As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that. ==Why?== As...

Development:Themes 2.0 how to make the dock horizontal

2011-03-17T04:57:33Z

Samhemelryk: /* dockmod.js */

{{Template:Themes}}{{Moodle 2.0}}This quick tutorial looks at how to move the dock from its vertical position on the left hand side of the screen to a horizontal position at the top of the screen.<br />
This modification will be done entirely within a theme through the creation of a small amount of JavaScript and a few lines of CSS.

==Getting started==

If you're new to Moodle and haven't yet read the tutorial on creating your first theme I strongly suggest you head there first.<br />
I'd also strongly suggest you read [[Development:Styling and customising the dock]] which explains the structure of the dock and a few of the things you will need to know in order to tackle this tutorial.

In order to make this tutorial easier to understand I am going to create a new theme that we'll call '''dockmod''' in which we will create this modification.
So first step within your Moodle theme directory create a new directory called ''dockmod''. Within this new directory we'll create two further directories JavaScript, and style.
You should now have a directory structure like the one shown below:
<pre>
moodle/theme/dockmod
moodle/theme/dockmod/javascript
moodle/theme/dockmod/style
</pre>

The next step is to create the three files we are going to need, config.php, dockmod.js, and dockmod.css.
# config.php is of course for our theme's configuration and as you know an essential for any theme.
# dockmod.js will be created in the JavaScript directory, this file will contain the bit of JavaScript we need to write to get our modification to work.
# dockmod.css will be created in the style directory, this file will contain the CSS we need in order to make the dock horizontal.

You should end up with the following files:
<pre>
moodle/theme/dockmod/config.php
moodle/theme/dockmod/javascript/dockmod.js
moodle/theme/dockmod/style/dockmod.css
</pre>

==config.php==
In this step we will be setting up the config.php file for this theme, to be truthful there should be nothing new here for you, this is the easy part of the tutorial.
The idea of this theme is to simply extend the standard theme and make the dock modification. This has the advantage that our theme will only consist of the JS and CSS required to achieve the dock modification we want.

So open the config.php file in your favourite editor and type the following in:
<code php>
<?php

/**
* This is the config file for the dockmod theme.
*/

$THEME->name = 'dockmod';
$THEME->sheets = array('dockmod');
$THEME->parents = array('standard', 'base');
$THEME->enable_dock = true;
$THEME->javascripts = array('dockmod');
</code>

So pretty simple really, the name of our theme is ''dockmod'', you already knew that!
The parents for this new theme are standard and base as explained above.
We have one stylesheet also called dockmod (theme/dockmod/style/dockmod.css), and we have one JavaScript file also called dockmod (theme/dockmod/javascript/dockmod.js) and of course its essential we enable the dock, otherwise there's no point in creating this modification.

==The JavaScript==
OK this is where the tutorial starts to enter the [potentially] unknown.

The dock is pretty cool in that it looks for a specific JavaScript function when it loads and calls it if it exists, we can use this to modify the dock as we want. It also published several events that we are able to listen to in order to make further modifications when certain things happen.

In our case we want to make the dock horizontal. Now this isn't actually as nasty as it sounds because in a limited way the dock supports this! When I first wrote the dock I had in mind that one day I would have time to extend the dock to make it moveable, as such I wrote some basic support into it to allow the position and orientation to be switched. I know that a few of you in the community who have looked at making a horizontal dock have found these properties. Functions that rely on the position or orientation of the dock such as making the titles vertical have code within them that checks it makes sense to do so based upon the values of those properties.
All in all this makes our modification a lot simpler as half the work is already done!

To start with open ''javascript/dockmod.js'' in your favourite editor and type the following:
<code javascript>
function customise_dock_for_theme() {
var dock = M.core_dock;
dock.cfg.position = 'top';
dock.cfg.orientation = 'horizontal';
}
</code>

And that is it; It sounds hard, but as you see really it is very easy (although as you get through this tutorial you will see we actually add a bit more JS later on).

So how this works:
<code javascript>
function customise_dock_for_theme() { .... }
</code>
As mentioned above when the dock first loads it looks for a function and calls it, well this is the function '''customise_dock_for_theme'''.

<code javascript>
var dock = M.core_dock;
</code>
Here we are collecting the dock into a variable. It is in this case available from the global M object.

<code javascript>
dock.cfg.position = 'top';
dock.cfg.orientation = 'horizontal';
</code>
These two lines set two configuration variables for the dock, the position and the orientation. There are several other config properties that perhaps will be explored within another document or tutorial.

==The CSS==
If you save you changes presently and view your theme in your browser you will likely see a big mess. That is because while the JavaScript supports a horizontal dock there is not yet any CSS to support displaying the dock horizontally.

Because of this we will need to write a bit of CSS to ensure the dock is displayed correctly.
Open ''style/dockmod.css'' in your favourite editor and type the following:
<code css>
body.has_dock {margin-top:30px;margin-left:0;}
body.has_dock_top_horizontal #dock {width:100%;height:30px;background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;border-right-width:0;border-bottom:1px solid #000;}
body.has_dock_top_horizontal #dock .dockeditem_container {margin-top:0;}
body.has_dock_top_horizontal #dock .dockeditem {display:inline-block;}
body.has_dock_top_horizontal #dock .dockeditem .dockedtitle {background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;background-position:0 10%;border-style:solid;border-width: 0 1px 0 0;border-color:#AAA;}
body.has_dock_top_horizontal #dock .dockeditem .dockedtitle h2 {margin:0 12px;line-height:30px;}
body.has_dock_top_horizontal #dock .dockeditem.firstdockitem {margin-left:10px;}
body.has_dock_top_horizontal #dock .dockeditem.firstdockitem .dockedtitle {border-left-width:1px;}
body.has_dock_top_horizontal #dock .controls {bottom:auto;right:10px;top:0;width:auto;line-height:30px;}
body.has_dock_top_horizontal #dock #dockeditempanel {position:absolute;}
</code>

That's it!

The first line of CSS is to correct the margin on the body that accommodates the dock, we need to remove the left margin and increase the top margin.
The other lines of CSS basically just correct change to horizontal images, change positioning from vertical to horizontal, and swap X/Y properties.

'''PLEASE NOTE:''' the above CSS using ''display:inline-block'' so this won't work in IE6/7, if this is a problem for anyone you could probably achieve something similar using floats.

==Correcting a vertical bug==
If you now open your site in your browser and switch to your theme you should see a horizontal dock.
If you have a bit of a play with if you will notice that if you dock the settings block and fully expand it it will run off the bottom of the page and there will be no scroll bar.
This has happened because we changed the position attributes of the dock in our CSS above. Essentially we could tinker with the CSS and try to fix it there, however based upon the design of the block and the complexities of getting it to work cross browser I can tell you it's going to be hard. Instead I'll show you how we can fix it in JavaScript.

Open your dockmod.js file again and type the following within the customize dock function below the three lines that are already in there.
<code javascript>
dock.on('dock:resizepanelcomplete', theme_dockmod_handle_resize);
</code>

This line of code is adding an event listener to the dock so that when it fires the '''dock:resizepanelcomplete''' event the function '''theme_dockmod_handle_resize''' which we create shortly will get called.

The ''resizepanelcomplete'' function gets called '''after''' the panel that shows the content of a block has been resized. The panel gets resized any time it's display changes, e.g. when it is shown, or when the content within the panel changes (you expand something).<br />
This event is perfect for our needs as when it is called we can look at the height of the panel and if it is more than the height of the screen we can add scrollbars to it and set the height so that the user can access all of the content of the panel.

Now we need to write the ''theme_dockmod_handle_resize'' function. Below the customize dock function type the following:
<code javascript>
function theme_dockmod_handle_resize() {
var dock = M.core_dock;
var panel = dock.getPanel();
var item = dock.getActiveItem();
// Check its visible no point doing anything if its not.
if (panel.visible === false || typeof(item) !== 'object') {
return;
}
var buffer = dock.cfg.buffer;
var screenheight = parseInt(dock.nodes.body.get('winHeight'))-(buffer*2)-dock.nodes.dock.get('offsetHeight');
var scrolltop = panel.contentBody.get('scrollTop');
// Reset the height of the panel so that we can accurately measure it
panel.contentBody.setStyle('height', 'auto');
// Remove the oversized class if it is there.
panel.removeClass('oversized_content');
var panelheight = panel.get('offsetHeight');
// Set the height of the panel if required and add the oversized class
if (panelheight > screenheight) {
panel.contentBody.setStyle('height', (screenheight - panel.contentHeader.get('offsetHeight'))+'px');
panel.addClass('oversized_content');
}
// Set the scrolltop of the panel to what it was before we started.
if (scrolltop) {
panel.contentBody.set('scrollTop', scrolltop);
}
}
</code>

Save the file now, purge the Moodle cache, and reload the page.
If you try to replicate the bug now you should find instead you get scrollbars and things work fine.

Congratulations, you've successfully created a horizontal dock!

==Complete source==
The following is the complete source files for this tutorial.
===config.php===
<code php>
<?php

/**
* This is the config file for the dockmod theme.
*/

$THEME->name = 'dockmod';
$THEME->sheets = array('dockmod');
$THEME->parents = array('standard', 'base');
$THEME->enable_dock = true;
$THEME->javascripts = array('dockmod');
</code>

===dockmod.css===
<code css>
body.has_dock {margin-top:30px;margin-left:0;}

/** This is the CSS to display the block on the top of the screen */
.has_dock_top_horizontal #dock {width:100%;height:30px;background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;border-right-width:0;border-bottom:1px solid #000;}
.has_dock_top_horizontal #dock .dockeditem_container {margin-top:0;}
.has_dock_top_horizontal #dock .dockeditem {display:inline-block;}
.has_dock_top_horizontal #dock .dockeditem .dockedtitle {background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;background-position:0 10%;border-style:solid;border-width: 0 1px 0 0;border-color:#AAA;}
.has_dock_top_horizontal #dock .dockeditem .dockedtitle h2 {margin:0 12px;line-height:30px;}
.has_dock_top_horizontal #dock .dockeditem.firstdockitem {margin-left:10px;}
.has_dock_top_horizontal #dock .dockeditem.firstdockitem .dockedtitle {border-left-width:1px;}
.has_dock_top_horizontal #dock .controls {bottom:auto;right:10px;top:0;width:auto;line-height:30px;}
.has_dock_top_horizontal #dock #dockeditempanel {position:absolute;}
</code>

===dockmod.js===
<code javascript>
function customise_dock_for_theme() {
var dock = M.core_dock;
dock.cfg.position = 'top';
dock.cfg.orientation = 'horizontal';
dock.on('dock:resizepanelcomplete', theme_dockmod_handle_resize);
}

function theme_dockmod_handle_resize() {
var dock = M.core_dock;
var panel = dock.getPanel();
var item = dock.getActiveItem();
// Check its visible no point doing anything if its not.
if (panel.visible === false || typeof(item) !== 'object') {
return;
}
var buffer = dock.cfg.buffer;
var screenheight = parseInt(dock.nodes.body.get('winHeight'))-(buffer*2)-dock.nodes.dock.get('offsetHeight');
var scrolltop = panel.contentBody.get('scrollTop');
// Reset the height of the panel so that we can accurately measure it
panel.contentBody.setStyle('height', 'auto');
// Remove the oversized class if it is there.
panel.removeClass('oversized_content');
var panelheight = panel.get('offsetHeight');
// Set the height of the panel if required and add the oversized class
if (panelheight > screenheight) {
panel.contentBody.setStyle('height', (screenheight - panel.contentHeader.get('offsetHeight'))+'px');
panel.addClass('oversized_content');
}
// Set the scrolltop of the panel to what it was before we started.
if (scrolltop) {
panel.contentBody.set('scrollTop', scrolltop);
}
}
</code>

==Creating a moveable dock==
A while ago I created theme that like this one supports a horizontal dock, however it goes one step further by adding a button above the undock all button that when clicked moves the down to the next position (without refreshing the page).

For those interested in having a look at that you can find it on my github account at: https://github.com/samhemelryk/moodle-theme_dockmod

==More information==

* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Styling and customising the dock]]

Development:Themes 2.0 how to make the dock horizontal

2011-03-16T03:02:26Z

Samhemelryk: /* The CSS */

{{Template:Themes}}{{Moodle 2.0}}This quick tutorial looks at how to move the dock from its vertical position on the left hand side of the screen to a horizontal position at the top of the screen.<br />
This modification will be done entirely within a theme through the creation of a small amount of JavaScript and a few lines of CSS.

==Getting started==

If you're new to Moodle and haven't yet read the tutorial on creating your first theme I strongly suggest you head there first.<br />
I'd also strongly suggest you read [[Development:Styling and customising the dock]] which explains the structure of the dock and a few of the things you will need to know in order to tackle this tutorial.

In order to make this tutorial easier to understand I am going to create a new theme that we'll call '''dockmod''' in which we will create this modification.
So first step within your Moodle theme directory create a new directory called ''dockmod''. Within this new directory we'll create two further directories JavaScript, and style.
You should now have a directory structure like the one shown below:
<pre>
moodle/theme/dockmod
moodle/theme/dockmod/javascript
moodle/theme/dockmod/style
</pre>

The next step is to create the three files we are going to need, config.php, dockmod.js, and dockmod.css.
# config.php is of course for our theme's configuration and as you know an essential for any theme.
# dockmod.js will be created in the JavaScript directory, this file will contain the bit of JavaScript we need to write to get our modification to work.
# dockmod.css will be created in the style directory, this file will contain the CSS we need in order to make the dock horizontal.

You should end up with the following files:
<pre>
moodle/theme/dockmod/config.php
moodle/theme/dockmod/javascript/dockmod.js
moodle/theme/dockmod/style/dockmod.css
</pre>

==config.php==
In this step we will be setting up the config.php file for this theme, to be truthful there should be nothing new here for you, this is the easy part of the tutorial.
The idea of this theme is to simply extend the standard theme and make the dock modification. This has the advantage that our theme will only consist of the JS and CSS required to achieve the dock modification we want.

So open the config.php file in your favourite editor and type the following in:
<code php>
<?php

/**
* This is the config file for the dockmod theme.
*/

$THEME->name = 'dockmod';
$THEME->sheets = array('dockmod');
$THEME->parents = array('standard', 'base');
$THEME->enable_dock = true;
$THEME->javascripts = array('dockmod');
</code>

So pretty simple really, the name of our theme is ''dockmod'', you already knew that!
The parents for this new theme are standard and base as explained above.
We have one stylesheet also called dockmod (theme/dockmod/style/dockmod.css), and we have one JavaScript file also called dockmod (theme/dockmod/javascript/dockmod.js) and of course its essential we enable the dock, otherwise there's no point in creating this modification.

==The JavaScript==
OK this is where the tutorial starts to enter the [potentially] unknown.

The dock is pretty cool in that it looks for a specific JavaScript function when it loads and calls it if it exists, we can use this to modify the dock as we want. It also published several events that we are able to listen to in order to make further modifications when certain things happen.

In our case we want to make the dock horizontal. Now this isn't actually as nasty as it sounds because in a limited way the dock supports this! When I first wrote the dock I had in mind that one day I would have time to extend the dock to make it moveable, as such I wrote some basic support into it to allow the position and orientation to be switched. I know that a few of you in the community who have looked at making a horizontal dock have found these properties. Functions that rely on the position or orientation of the dock such as making the titles vertical have code within them that checks it makes sense to do so based upon the values of those properties.
All in all this makes our modification a lot simpler as half the work is already done!

To start with open ''javascript/dockmod.js'' in your favourite editor and type the following:
<code javascript>
function customise_dock_for_theme() {
var dock = M.core_dock;
dock.cfg.position = 'top';
dock.cfg.orientation = 'horizontal';
}
</code>

And that is it; It sounds hard, but as you see really it is very easy (although as you get through this tutorial you will see we actually add a bit more JS later on).

So how this works:
<code javascript>
function customise_dock_for_theme() { .... }
</code>
As mentioned above when the dock first loads it looks for a function and calls it, well this is the function '''customise_dock_for_theme'''.

<code javascript>
var dock = M.core_dock;
</code>
Here we are collecting the dock into a variable. It is in this case available from the global M object.

<code javascript>
dock.cfg.position = 'top';
dock.cfg.orientation = 'horizontal';
</code>
These two lines set two configuration variables for the dock, the position and the orientation. There are several other config properties that perhaps will be explored within another document or tutorial.

==The CSS==
If you save you changes presently and view your theme in your browser you will likely see a big mess. That is because while the JavaScript supports a horizontal dock there is not yet any CSS to support displaying the dock horizontally.

Because of this we will need to write a bit of CSS to ensure the dock is displayed correctly.
Open ''style/dockmod.css'' in your favourite editor and type the following:
<code css>
body.has_dock {margin-top:30px;margin-left:0;}
body.has_dock_top_horizontal #dock {width:100%;height:30px;background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;border-right-width:0;border-bottom:1px solid #000;}
body.has_dock_top_horizontal #dock .dockeditem_container {margin-top:0;}
body.has_dock_top_horizontal #dock .dockeditem {display:inline-block;}
body.has_dock_top_horizontal #dock .dockeditem .dockedtitle {background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;background-position:0 10%;border-style:solid;border-width: 0 1px 0 0;border-color:#AAA;}
body.has_dock_top_horizontal #dock .dockeditem .dockedtitle h2 {margin:0 12px;line-height:30px;}
body.has_dock_top_horizontal #dock .dockeditem.firstdockitem {margin-left:10px;}
body.has_dock_top_horizontal #dock .dockeditem.firstdockitem .dockedtitle {border-left-width:1px;}
body.has_dock_top_horizontal #dock .controls {bottom:auto;right:10px;top:0;width:auto;line-height:30px;}
body.has_dock_top_horizontal #dock #dockeditempanel {position:absolute;}
</code>

That's it!

The first line of CSS is to correct the margin on the body that accommodates the dock, we need to remove the left margin and increase the top margin.
The other lines of CSS basically just correct change to horizontal images, change positioning from vertical to horizontal, and swap X/Y properties.

'''PLEASE NOTE:''' the above CSS using ''display:inline-block'' so this won't work in IE6/7, if this is a problem for anyone you could probably achieve something similar using floats.

==Correcting a vertical bug==
If you now open your site in your browser and switch to your theme you should see a horizontal dock.
If you have a bit of a play with if you will notice that if you dock the settings block and fully expand it it will run off the bottom of the page and there will be no scroll bar.
This has happened because we changed the position attributes of the dock in our CSS above. Essentially we could tinker with the CSS and try to fix it there, however based upon the design of the block and the complexities of getting it to work cross browser I can tell you it's going to be hard. Instead I'll show you how we can fix it in JavaScript.

Open your dockmod.js file again and type the following within the customize dock function below the three lines that are already in there.
<code javascript>
dock.on('dock:resizepanelcomplete', theme_dockmod_handle_resize);
</code>

This line of code is adding an event listener to the dock so that when it fires the '''dock:resizepanelcomplete''' event the function '''theme_dockmod_handle_resize''' which we create shortly will get called.

The ''resizepanelcomplete'' function gets called '''after''' the panel that shows the content of a block has been resized. The panel gets resized any time it's display changes, e.g. when it is shown, or when the content within the panel changes (you expand something).<br />
This event is perfect for our needs as when it is called we can look at the height of the panel and if it is more than the height of the screen we can add scrollbars to it and set the height so that the user can access all of the content of the panel.

Now we need to write the ''theme_dockmod_handle_resize'' function. Below the customize dock function type the following:
<code javascript>
function theme_dockmod_handle_resize() {
var dock = M.core_dock;
var panel = dock.getPanel();
var item = dock.getActiveItem();
// Check its visible no point doing anything if its not.
if (panel.visible === false || typeof(item) !== 'object') {
return;
}
var buffer = dock.cfg.buffer;
var screenheight = parseInt(dock.nodes.body.get('winHeight'))-(buffer*2)-dock.nodes.dock.get('offsetHeight');
var scrolltop = panel.contentBody.get('scrollTop');
// Reset the height of the panel so that we can accurately measure it
panel.contentBody.setStyle('height', 'auto');
// Remove the oversized class if it is there.
panel.removeClass('oversized_content');
var panelheight = panel.get('offsetHeight');
// Set the height of the panel if required and add the oversized class
if (panelheight > screenheight) {
panel.contentBody.setStyle('height', (screenheight - panel.contentHeader.get('offsetHeight'))+'px');
panel.addClass('oversized_content');
}
// Set the scrolltop of the panel to what it was before we started.
if (scrolltop) {
panel.contentBody.set('scrollTop', scrolltop);
}
}
</code>

Save the file now, purge the Moodle cache, and reload the page.
If you try to replicate the bug now you should find instead you get scrollbars and things work fine.

Congratulations, you've successfully created a horizontal dock!

==Complete source==
The following is the complete source files for this tutorial.
===config.php===
<code php>
<?php

/**
* This is the config file for the dockmod theme.
*/

$THEME->name = 'dockmod';
$THEME->sheets = array('dockmod');
$THEME->parents = array('standard', 'base');
$THEME->enable_dock = true;
$THEME->javascripts = array('dockmod');
</code>

===dockmod.css===
<code css>
body.has_dock {margin-top:30px;margin-left:0;}

/** This is the CSS to display the block on the top of the screen */
.has_dock_top_horizontal #dock {width:100%;height:30px;background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;border-right-width:0;border-bottom:1px solid #000;}
.has_dock_top_horizontal #dock .dockeditem_container {margin-top:0;}
.has_dock_top_horizontal #dock .dockeditem {display:inline-block;}
.has_dock_top_horizontal #dock .dockeditem .dockedtitle {background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;background-position:0 10%;border-style:solid;border-width: 0 1px 0 0;border-color:#AAA;}
.has_dock_top_horizontal #dock .dockeditem .dockedtitle h2 {margin:0 12px;line-height:30px;}
.has_dock_top_horizontal #dock .dockeditem.firstdockitem {margin-left:10px;}
.has_dock_top_horizontal #dock .dockeditem.firstdockitem .dockedtitle {border-left-width:1px;}
.has_dock_top_horizontal #dock .controls {bottom:auto;right:10px;top:0;width:auto;line-height:30px;}
.has_dock_top_horizontal #dock #dockeditempanel {position:absolute;}
</code>

===dockmod.js===
<code javascript>
function theme_dockmod_handle_resize() {
var dock = M.core_dock;
var panel = dock.getPanel();
var item = dock.getActiveItem();
// Check its visible no point doing anything if its not.
if (panel.visible === false || typeof(item) !== 'object') {
return;
}
var buffer = dock.cfg.buffer;
var screenheight = parseInt(dock.nodes.body.get('winHeight'))-(buffer*2)-dock.nodes.dock.get('offsetHeight');
var scrolltop = panel.contentBody.get('scrollTop');
// Reset the height of the panel so that we can accurately measure it
panel.contentBody.setStyle('height', 'auto');
// Remove the oversized class if it is there.
panel.removeClass('oversized_content');
var panelheight = panel.get('offsetHeight');
// Set the height of the panel if required and add the oversized class
if (panelheight > screenheight) {
panel.contentBody.setStyle('height', (screenheight - panel.contentHeader.get('offsetHeight'))+'px');
panel.addClass('oversized_content');
}
// Set the scrolltop of the panel to what it was before we started.
if (scrolltop) {
panel.contentBody.set('scrollTop', scrolltop);
}
}
</code>

==Creating a moveable dock==
A while ago I created theme that like this one supports a horizontal dock, however it goes one step further by adding a button above the undock all button that when clicked moves the down to the next position (without refreshing the page).

For those interested in having a look at that you can find it on my github account at: https://github.com/samhemelryk/moodle-theme_dockmod

==More information==

* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Styling and customising the dock]]

Development:Themes 2.0 how to make the dock horizontal

2011-03-16T02:57:23Z

Samhemelryk: Added categories and theme template

{{Template:Themes}}{{Moodle 2.0}}This quick tutorial looks at how to move the dock from its vertical position on the left hand side of the screen to a horizontal position at the top of the screen.<br />
This modification will be done entirely within a theme through the creation of a small amount of JavaScript and a few lines of CSS.

==Getting started==

If you're new to Moodle and haven't yet read the tutorial on creating your first theme I strongly suggest you head there first.<br />
I'd also strongly suggest you read [[Development:Styling and customising the dock]] which explains the structure of the dock and a few of the things you will need to know in order to tackle this tutorial.

In order to make this tutorial easier to understand I am going to create a new theme that we'll call '''dockmod''' in which we will create this modification.
So first step within your Moodle theme directory create a new directory called ''dockmod''. Within this new directory we'll create two further directories JavaScript, and style.
You should now have a directory structure like the one shown below:
<pre>
moodle/theme/dockmod
moodle/theme/dockmod/javascript
moodle/theme/dockmod/style
</pre>

The next step is to create the three files we are going to need, config.php, dockmod.js, and dockmod.css.
# config.php is of course for our theme's configuration and as you know an essential for any theme.
# dockmod.js will be created in the JavaScript directory, this file will contain the bit of JavaScript we need to write to get our modification to work.
# dockmod.css will be created in the style directory, this file will contain the CSS we need in order to make the dock horizontal.

You should end up with the following files:
<pre>
moodle/theme/dockmod/config.php
moodle/theme/dockmod/javascript/dockmod.js
moodle/theme/dockmod/style/dockmod.css
</pre>

==config.php==
In this step we will be setting up the config.php file for this theme, to be truthful there should be nothing new here for you, this is the easy part of the tutorial.
The idea of this theme is to simply extend the standard theme and make the dock modification. This has the advantage that our theme will only consist of the JS and CSS required to achieve the dock modification we want.

So open the config.php file in your favourite editor and type the following in:
<code php>
<?php

/**
* This is the config file for the dockmod theme.
*/

$THEME->name = 'dockmod';
$THEME->sheets = array('dockmod');
$THEME->parents = array('standard', 'base');
$THEME->enable_dock = true;
$THEME->javascripts = array('dockmod');
</code>

So pretty simple really, the name of our theme is ''dockmod'', you already knew that!
The parents for this new theme are standard and base as explained above.
We have one stylesheet also called dockmod (theme/dockmod/style/dockmod.css), and we have one JavaScript file also called dockmod (theme/dockmod/javascript/dockmod.js) and of course its essential we enable the dock, otherwise there's no point in creating this modification.

==The JavaScript==
OK this is where the tutorial starts to enter the [potentially] unknown.

The dock is pretty cool in that it looks for a specific JavaScript function when it loads and calls it if it exists, we can use this to modify the dock as we want. It also published several events that we are able to listen to in order to make further modifications when certain things happen.

In our case we want to make the dock horizontal. Now this isn't actually as nasty as it sounds because in a limited way the dock supports this! When I first wrote the dock I had in mind that one day I would have time to extend the dock to make it moveable, as such I wrote some basic support into it to allow the position and orientation to be switched. I know that a few of you in the community who have looked at making a horizontal dock have found these properties. Functions that rely on the position or orientation of the dock such as making the titles vertical have code within them that checks it makes sense to do so based upon the values of those properties.
All in all this makes our modification a lot simpler as half the work is already done!

To start with open ''javascript/dockmod.js'' in your favourite editor and type the following:
<code javascript>
function customise_dock_for_theme() {
var dock = M.core_dock;
dock.cfg.position = 'top';
dock.cfg.orientation = 'horizontal';
}
</code>

And that is it; It sounds hard, but as you see really it is very easy (although as you get through this tutorial you will see we actually add a bit more JS later on).

So how this works:
<code javascript>
function customise_dock_for_theme() { .... }
</code>
As mentioned above when the dock first loads it looks for a function and calls it, well this is the function '''customise_dock_for_theme'''.

<code javascript>
var dock = M.core_dock;
</code>
Here we are collecting the dock into a variable. It is in this case available from the global M object.

<code javascript>
dock.cfg.position = 'top';
dock.cfg.orientation = 'horizontal';
</code>
These two lines set two configuration variables for the dock, the position and the orientation. There are several other config properties that perhaps will be explored within another document or tutorial.

==The CSS==
If you save you changes presently and view your theme in your browser you will likely see a big mess. That is because while the JavaScript supports a horizontal dock there is not yet any CSS to support displaying the dock horizontally.

Because of this we will need to write a bit of CSS to ensure the dock is displayed correctly.
Open ''style/dockmod.css'' in your favourite editor and type the following:
<code css>
body.has_dock {margin-top:30px;margin-left:0;}
body.has_dock_top_horizontal #dock {width:100%;height:30px;background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;border-right-width:0;border-bottom:1px solid #000;}
body.has_dock_top_horizontal #dock .dockeditem_container {margin-top:0;}
body.has_dock_top_horizontal #dock .dockeditem {display:inline-block;}
body.has_dock_top_horizontal #dock .dockeditem .dockedtitle {background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;background-position:0 10%;border-style:solid;border-width: 0 1px 0 0;border-color:#AAA;}
body.has_dock_top_horizontal #dock .dockeditem .dockedtitle h2 {margin:0 12px;line-height:30px;}
body.has_dock_top_horizontal #dock .dockeditem.firstdockitem {margin-left:10px;}
body.has_dock_top_horizontal #dock .dockeditem.firstdockitem .dockedtitle {border-left-width:1px;}
body.has_dock_top_horizontal #dock .controls {bottom:auto;right:10px;top:0;width:auto;line-height:30px;}
body.has_dock_top_horizontal #dock #dockeditempanel {position:absolute;}
</code>

That's it!

The first line of CSS is to correct the margin on the body that accommodates the dock, we need to remove the left margin and increase the top margin.
The other lines of CSS basically just correct change to horizontal images, change positioning from vertical to horizontal, and swap X/Y properties.

==Correcting a vertical bug==
If you now open your site in your browser and switch to your theme you should see a horizontal dock.
If you have a bit of a play with if you will notice that if you dock the settings block and fully expand it it will run off the bottom of the page and there will be no scroll bar.
This has happened because we changed the position attributes of the dock in our CSS above. Essentially we could tinker with the CSS and try to fix it there, however based upon the design of the block and the complexities of getting it to work cross browser I can tell you it's going to be hard. Instead I'll show you how we can fix it in JavaScript.

Open your dockmod.js file again and type the following within the customize dock function below the three lines that are already in there.
<code javascript>
dock.on('dock:resizepanelcomplete', theme_dockmod_handle_resize);
</code>

This line of code is adding an event listener to the dock so that when it fires the '''dock:resizepanelcomplete''' event the function '''theme_dockmod_handle_resize''' which we create shortly will get called.

The ''resizepanelcomplete'' function gets called '''after''' the panel that shows the content of a block has been resized. The panel gets resized any time it's display changes, e.g. when it is shown, or when the content within the panel changes (you expand something).<br />
This event is perfect for our needs as when it is called we can look at the height of the panel and if it is more than the height of the screen we can add scrollbars to it and set the height so that the user can access all of the content of the panel.

Now we need to write the ''theme_dockmod_handle_resize'' function. Below the customize dock function type the following:
<code javascript>
function theme_dockmod_handle_resize() {
var dock = M.core_dock;
var panel = dock.getPanel();
var item = dock.getActiveItem();
// Check its visible no point doing anything if its not.
if (panel.visible === false || typeof(item) !== 'object') {
return;
}
var buffer = dock.cfg.buffer;
var screenheight = parseInt(dock.nodes.body.get('winHeight'))-(buffer*2)-dock.nodes.dock.get('offsetHeight');
var scrolltop = panel.contentBody.get('scrollTop');
// Reset the height of the panel so that we can accurately measure it
panel.contentBody.setStyle('height', 'auto');
// Remove the oversized class if it is there.
panel.removeClass('oversized_content');
var panelheight = panel.get('offsetHeight');
// Set the height of the panel if required and add the oversized class
if (panelheight > screenheight) {
panel.contentBody.setStyle('height', (screenheight - panel.contentHeader.get('offsetHeight'))+'px');
panel.addClass('oversized_content');
}
// Set the scrolltop of the panel to what it was before we started.
if (scrolltop) {
panel.contentBody.set('scrollTop', scrolltop);
}
}
</code>

Save the file now, purge the Moodle cache, and reload the page.
If you try to replicate the bug now you should find instead you get scrollbars and things work fine.

Congratulations, you've successfully created a horizontal dock!

==Complete source==
The following is the complete source files for this tutorial.
===config.php===
<code php>
<?php

/**
* This is the config file for the dockmod theme.
*/

$THEME->name = 'dockmod';
$THEME->sheets = array('dockmod');
$THEME->parents = array('standard', 'base');
$THEME->enable_dock = true;
$THEME->javascripts = array('dockmod');
</code>

===dockmod.css===
<code css>
body.has_dock {margin-top:30px;margin-left:0;}

/** This is the CSS to display the block on the top of the screen */
.has_dock_top_horizontal #dock {width:100%;height:30px;background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;border-right-width:0;border-bottom:1px solid #000;}
.has_dock_top_horizontal #dock .dockeditem_container {margin-top:0;}
.has_dock_top_horizontal #dock .dockeditem {display:inline-block;}
.has_dock_top_horizontal #dock .dockeditem .dockedtitle {background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;background-position:0 10%;border-style:solid;border-width: 0 1px 0 0;border-color:#AAA;}
.has_dock_top_horizontal #dock .dockeditem .dockedtitle h2 {margin:0 12px;line-height:30px;}
.has_dock_top_horizontal #dock .dockeditem.firstdockitem {margin-left:10px;}
.has_dock_top_horizontal #dock .dockeditem.firstdockitem .dockedtitle {border-left-width:1px;}
.has_dock_top_horizontal #dock .controls {bottom:auto;right:10px;top:0;width:auto;line-height:30px;}
.has_dock_top_horizontal #dock #dockeditempanel {position:absolute;}
</code>

===dockmod.js===
<code javascript>
function theme_dockmod_handle_resize() {
var dock = M.core_dock;
var panel = dock.getPanel();
var item = dock.getActiveItem();
// Check its visible no point doing anything if its not.
if (panel.visible === false || typeof(item) !== 'object') {
return;
}
var buffer = dock.cfg.buffer;
var screenheight = parseInt(dock.nodes.body.get('winHeight'))-(buffer*2)-dock.nodes.dock.get('offsetHeight');
var scrolltop = panel.contentBody.get('scrollTop');
// Reset the height of the panel so that we can accurately measure it
panel.contentBody.setStyle('height', 'auto');
// Remove the oversized class if it is there.
panel.removeClass('oversized_content');
var panelheight = panel.get('offsetHeight');
// Set the height of the panel if required and add the oversized class
if (panelheight > screenheight) {
panel.contentBody.setStyle('height', (screenheight - panel.contentHeader.get('offsetHeight'))+'px');
panel.addClass('oversized_content');
}
// Set the scrolltop of the panel to what it was before we started.
if (scrolltop) {
panel.contentBody.set('scrollTop', scrolltop);
}
}
</code>

==Creating a moveable dock==
A while ago I created theme that like this one supports a horizontal dock, however it goes one step further by adding a button above the undock all button that when clicked moves the down to the next position (without refreshing the page).

For those interested in having a look at that you can find it on my github account at: https://github.com/samhemelryk/moodle-theme_dockmod

==More information==

* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Styling and customising the dock]]

Development:Styling and customising the dock

2011-03-16T02:56:32Z

Samhemelryk: /* Tutorial: Creating a moveable dock */

{{Template:Themes}}{{Moodle 2.0}}The dock is a new addition to Moodle 2.0, it allows the user to move blocks from the flow of the page onto a special bar that is displayed in a constant position on the side of the page by default.
This document looks at how to style the dock using CSS, as well as how to customise or manipulate it within JavaScript.

==Styling the dock==
Styling the dock is really no different to styling anything else within a web site however there are a couple of things that may slow you down and reading the following document may help you in your understanding of how the dock works and how you should go about styling it.

The following items are things that you should be aware of before starting to style the dock:
# When a block is docked the dock attempts to ensure that existing styles for the block are still applied by adding the standard block '''.block_''blockname'''''. Because of this trick we don't need to look at the actual content of a docked item it will always be the same as the block.
# The dock remembers what blocks are docked by saving the user's choices within the database using AJAX calls. This can be looked at to minimise display jumping within a theme's layoutfile. Read on to learn how.
# The dock uses CSS classes to transition the different states. These CSS classes control things such as the whether the dock is visible, whether the panel is visible, and how we know which item is being viewed. Read the section on [[#State_classes|state classes]] to learn more about these.
# The structure of the dock is built entirely by JavaScript. Because of this you will need a tool such as FireBug to inspect it within a page as it won't be there until JavaScript has run.
# Although the base theme doesn't support the dock it does contain some core CSS to structure the dock by default.

So lets get started and look at the structure.
===The structure of the dock===
[[Image:Dock.structure.201005.png|300px|thumb|Dock structure]]
The first image to the left graphically describes the hierarchical structure of the dock. The first thing you will notice about this image is that it doesn't describe what each element is for. It is just to illustrate the html structure without at styles or transformation.

So what are the important elements here?

; div#dock.dock.dock_left_vertical : This is the bar on the left. Positioned by default to be fixed position in the top left hand corner of the screen and 30px wide.
; div.dockeditem_container : This box contains all of the buttons which when clicked or hovered over will display the docked item. Or more technically causing the docked item panel to be shown.
; div#dock_item_x.dockeditem : This represents one of possibly several docked item buttons containing the title of the docked item. There are two things to note about this element: First it is repeated for every docked item. Second the x within the id is the item instance and should not be used for styling.
; div.controls : This contains any special controls for the dock and by default is displayed at the bottom of the dock. As of Moodle 2 Preview Release the only control here is to undock all docked items.
; div#dockeditempanel : This is the panel in which docked items are shown. Although it is within the dock is it positioned outside of the page relative to the button for the item it is currently showing. This element is based loosely off the YUI3 overlay.

===The layout of the dock===
[[Image:Dock.layout.201005.png|300px|thumb|Dock layout]]
The second image on the left shows the layout of these elements within the standard theme.

'''So what has gone on here?'''
First up ignore the bright colours and margins. I have put these colours in simply to highlight everything and ensure there is space between elements so I can show them apart.

; div#dock : So immediately you notice that the dock is in the top left of the screen and the is fixed width. This is achieved by setting a strict with of 30px and setting the position of the ''#dock'' to fixed. The reason that everything is within the one ''#dock'' element is because it makes positioning everything very simple, now that we have set the position of ''#dock'' we don't need to worry about anything other than the panel which we'll get to shortly. You should also note that because of the strict width and position you need to be careful when applying styles to this element as it can have nasty effects on everything else.

; div.dockeditem_container : Next you should notice that the ''.dockeditem_container'' doesn't extend to the bottom of the dock. Because there is not special positioning here it is behaving as div's normally do and this is the perfect place to really start styling your dock.

; div.controls : After that within the structure we have ''div.controls''. This element is positioned absolutely at the bottom of the dock, is 100% wide (so the full width of the dock) and uses ''text-align:center'' to ensure that the controls are centred.

; div.dockeditem : Simply representing a button that can be hovered over or clicked to display the docked item the only important thing to note about this is that you should change the cursor to a pointer so that it is clear you can interact with it.

; div#dockeditempanel : After ''#dock'' this is the most serious element in the dock. This element will contain the docked item and needs to positioned to the left of the dock and at the same height as the title of the item that is being displayed. Luckily you don't need to worry about the top position of the element that will be automatically adjusted by JavaScript however you will need to push the element to the left. This can be done easily by setting the position of the element to relative, and then setting left to 100%. Note you shouldn't style this element unless you know what you are doing, like the main dock element the smallest change can cause some terrible effects.

; div.dockeditempanel_container : This element is there specifically to give you the themer an easy place to start styling the panel.

; div.dockeditempanel_hd : This element contains the title of the docked item plus controls to undock or close it.

; div.dockeditempanel_bd : Contains is the main content area for the panel.

===State classes===
There are several state classes that the dock makes use of to achieve things such as the visibility of the dock, visibility of the panel, and which item is active.
The following table illustrates where these state classes are used.
{| class="nicetable"
! Element
! Class
! Description
! Default CSS
|-
|body
|has_dock
|This class is added to the body element when the dock is visible.
|Margin-left: 30px
|-
|#dock
|nothingdocked
|This class is added to the dock when there is nothing docked.
|visibility: hidden; display: none;
|-
|#dock
|.dock_''position''_''style''
|A special class is added to describe the docks desired position e.g. dock_left_vertical
|
|-
|.dockeditem
|activeitem
|This class is added to the item that is currently being shown.
|Change the background colour
|-
|.dockeditem
|firstdockitem
|This class is added to the first dock item.
|
|-
|.dockeditem h2
|filterrotate
|Added when the title is being rotated by an IE filter [Internet Explorer only]
|
|-
|#dockeditempanel
|dockitempanel_hidden
|Added to the panel when it is not being shown.
|visibility: hidden; display: none;
|-
|#dockeditempanel
|oversized_content
|Added when the panel required scrolling to show everything.
|Set the overflow method
|}

===Layout file changes===
There is only one thing that you need to make sure of within your layout files if you are creating your own. You need to add the class ''block-region'' to all of the block region div's as shown below.
<code php>
<div id="region-post" class="block-region">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
</code>
Whilst there is nothing else you '''need''' to change within your layout files there one other thing that you may want to do.

Because the dock is loaded entirely by JavaScript you will notice a visual jump on the page if all of the blocks within a region have been docked. This is because the dock shrinks sections that have been completely docked so that they don't wast page space.

Within you layout files you can check whether a section has been completely docked and then if it has set the body classes so that it is shrunk when the page is delivered.

I'm going to assume that you have all read the [[Development:Themes 2.0 creating your first theme]]. If you haven't go read it now.
So now that you've created your first theme think back to the code you wrote at the top of your layout files that checks whether a page has block regions pre and post. The code was as follows:
<code php>
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
</code>
Right below these two lines we are going to add two more:
<code php>
$showsidepre = ($hassidepre && !$PAGE->blocks->region_completely_docked('side-pre', $OUTPUT));
$showsidepost = ($hassidepost && !$PAGE->blocks->region_completely_docked('side-post', $OUTPUT));
</code>
What we have here is two variables that tell use whether we should show the block regions pre and post. The verbal interpretation of this string is to say ''We will show this side if this side has content and if there is at least one block that has not been docked.'' and we repeat it for each side.

Now that we know for each region that it has content and that we should show it we need some way to tell the page what block regions to show.
This is achieved by adding special classes to the body element of the page as follows:
; side-pre-only : This gets added to the body if we only want to show the block region pre.
; side-post-only : Just like side-pre-only except for the post region.
; content-only : This gets added if don't want to show either block region.
By default we want to show both regions so we don't need to add any class for this.
So how to do this in PHP?
<code php>
$bodyclasses = array();
if ($showsidepre && !$showsidepost) {
$bodyclasses[] = 'side-pre-only';
} else if ($showsidepost && !$showsidepre) {
$bodyclasses[] = 'side-post-only';
} else if (!$showsidepost && !$showsidepre) {
$bodyclasses[] = 'content-only';
}
</code>
What we have here is three if-else statements, of which either one or none will be true.
# The first if statement says if we want to show the pre region but not the post region add the class ''side-pre-only''
# The second if statement says if we want to show the post region but not the pre region add the class ''side-post-only''
# The third class says if we don't want to display either region add the class ''content-only''

Now that we know which class we want to add to the body element we need to do so. This can be done as follows:
<code php>
<body id="<?php echo $PAGE->bodyid ?>" class="<?php echo $PAGE->bodyclasses.' '.join(' ', $bodyclasses) ?>">
</code>
You'll notice this is very similar to the body tag you wrote in your first theme, however we have added
<code php>
join(' ', $bodyclasses)
</code>
This php command simply concatenates each body class putting a space between each.

Now the final thing to do is make sure that we don't show a block region if we don't have content for it. This can be done by adding if statements around each block region as follows:
<code php>
<?php if ($hassidepre) { ?>
<div id="region-pre" class="block-region">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post" class="block-region">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</code>
For each if statement we are saying ''If this region has content display it.'' You'll notice that here we are using ''$hasside...'' instead of ''$showside...'' this is because we want to add them if they have content even if they won't be shown. Otherwise the dock won't be able to find them and you simply won't see the block.

Having made the above changes if you now look at the layout files for the base theme you start to notice that they are looking very similar and indeed they are. If at any point you get stuck or don't know how to proceed have a look at the base themes layout files and see how its done there.

===The core CSS===
As mentioned in the key points at the start of this document the base theme although not supporting the dock does contain structural CSS that ensure the dock is functional on all themes that choose to support it.
Lets look at the CSS within ''theme/base/style/dock.css'', this is the core structural CSS for the dock.
<code css>
/* Put a margin on the body if the dock is shown */
body.has_dock {margin-left:30px;}
</code>
Well this is very simple, if the dock is being shown apply a 30px margin to the body. This is done to ensure that the dock doesn't overlap the body.

<code css>
/** For the dock itself */
#dock {width:30px;position:fixed;top:0px;left:0px;height:100%;background-color:#FFF;border-right:1px solid #000;z-index:11000;}
#dock.nothingdocked {visibility: hidden;display:none;}
</code>
These two rules style the dock itself. Note the second rule is only applied when nothing is docked in which case we will hide the empty dock.

<code css>
#dock .dockeditem .firstdockitem {margin-top:1em;}
#dock .dockeditem .dockedtitle {border-bottom:1px solid #000;border-top:1px solid #000;cursor:pointer;}
#dock .dockeditem .dockedtitle h2 {font-size:0.8em;line-height:100%;text-align:center;}
#dock .dockeditem .dockedtitle .filterrotate {margin-left:8px;}
</code>
The four rules above style the buttons that will show the docked items. Each docked item has one. The styles being used here arn't doing anything to special other than setting the cursor to pointer so that it is recognised as an actionable element.

<code css>
#dock .controls {position:absolute;bottom:1em;text-align:center;width:100%;}
#dock .controls img {cursor:pointer;}
</code>
Very simply this bit of CSS. It is positioning the controls for the dock at the bottom centre of the dock.

<code css>
/** For the panel the docked blocks are shown in */
#dockeditempanel {min-width:200px;position:relative;z-index:12000;left:100%;}
#dockeditempanel.dockitempanel_hidden {display:none;}
</code>
These two lines are applied to the docked item panel's base element and are VERY important to the operation of the dock. They ensure that when shown the panel is top the left of the dock and that when it is not being displayed it is not visible.

<code css>
#dockeditempanel .dockeditempanel_content {background-color:#fff;border:1px solid #000;z-index:12050;}
#dockeditempanel .dockeditempanel_bd {overflow:auto;width:auto;}
#dockeditempanel .dockeditempanel_bd .block_docked {margin:10px;}
#dockeditempanel .dockeditempanel_hd {border-bottom:1px solid #000;text-align:right;}
#dockeditempanel .dockeditempanel_hd h2 {display:inline;margin:0;padding-right:1em;}
#dockeditempanel .dockeditempanel_hd .commands {display:inline;}
#dockeditempanel .dockeditempanel_hd .commands img {margin-right:2px;vertical-align:middle;}
</code>
The above lines of CSS are used to style the internal content of the panel. Note the styles for the block will be applied as if it were not docked.

And that is it!

Whilst things don't look to difficult when styling things if you don't think carefully about where you are applying styles you can quickly dig yourself a big hole. I would suggest going slowly at first when applying more styles and making sure you don't apply too many styles to the base elements #dock and #dockeditempanel.

==Customising the dock==
This section of the document looks at how to customise the dock using JavaScript.

It was recognised early on during the development of the dock that it probably won't suit everyone's needs, nor would it appeal to everyone. Because of this during development and the frequent revisions that were occurring during Moodle 2.0s development there was always a focus on ensuring the dock was customisable and that someone with a bit of time on their hands and a good knowledge of JavaScript could hack it to bits and make it into the tool they desired.

This document doesn't go into the full details of how to customise the dock but should get anyone keen started quickly. Those who fear JavaScript should leave now!

===Getting started===
The dock is written to make use of YUI3 and all the functionality that it has to offer, the main dock object both looks for specific callback functions and adds manages and fires several important events. At the same time it is also object orientated JavaScript which has the advantage in JavaScript of allowing subsequent JavaScript events to redefine methods of the object.

This allows you the theme designer to write JavaScript to customise the dock in two fashions. The first through events and callbacks. The second through manually overriding the methods the dock uses.

We will look into these two methods in the subsequent sections of this document, for the time being what you need to learn about is the JavaScript structure of the dock.

First all of the code for the dock within Moodle 2.0 is located within the file '''moodle/blocks/dock.js''' and can be viewed online through the CVS repository[http://cvs.moodle.org/moodle/blocks/dock.js?view=markup]

There are three main objects that get used for the dock:
# First up is of course the dock, which is namespaced to M.core_dock.dock. It is instantiated only once per page and is essentially a static object that manages and operates the dock plus everything on it.
# Second is a generic block class. Every block on the page gets instantiated as a generic block unless it has a more specific class (that should extend the generic block class). This generic block class is responsible for moving a block between the dock and its normal block position. It is namespaced to M.core_dock.generic_block.
# The third class is the dock item class which is used to represent an item on the dock. It is responsible for showing the item when required and handles the events that the dock + user trigger. I can hear you asking now why not just add this functionality to the generic block class? because this keeps it open for things other than blocks to be docked.

As well as the above three classes there are some important class objects and properties that you should also be aware of as you may want to work with them when customising the dock.
; M.core_dock.Y : Is a YUI instance for use with the dock.
; M.core_dock.nodes.dock : Is the façade for the dock itself (#dock) and is a YUI3 Node instance.
; M.core_dock.getPanel() : This will return the panel that is used to display docked item within. It is stored locally through M.core_dock.nodes.panel however as it is not initialised until it is required you should always use the getPanel method.

The following are other important notes about the dock that you should read and understand before customising the dock.
# The dock emulates the YUI3 '''on''' method for listening to events. Because the dock requires initialisation which may occur through module dependencies we needed a method of exposing the dock to events prior to initialisation and this is it. It ensures that if you attach events to the dock before it is initialised everything still works fine.
# Both the dock and the item class inherit from Y.EventTarget and publish several events.
# The dock is designed to work both on old and modern browsers and as such there are several places where we branch based on browser and version.
# The generic block class should never be added to for the needs of a single block. Only things that are generic to all blocks should be added to this class. Independent needs should be handled by creating a block specific class that extends the generic block class. The navigation and settings blocks do this currently.

===Extending the dock through events===
Under construction

===Using custom methods for the dock===
Under construction

==More information==

* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 how to make the dock horizontal]] - Modifying the dock to make it horizontal.

Development:Styling and customising the dock

2011-03-16T02:56:14Z

Samhemelryk: /* More information */

{{Template:Themes}}{{Moodle 2.0}}The dock is a new addition to Moodle 2.0, it allows the user to move blocks from the flow of the page onto a special bar that is displayed in a constant position on the side of the page by default.
This document looks at how to style the dock using CSS, as well as how to customise or manipulate it within JavaScript.

==Styling the dock==
Styling the dock is really no different to styling anything else within a web site however there are a couple of things that may slow you down and reading the following document may help you in your understanding of how the dock works and how you should go about styling it.

The following items are things that you should be aware of before starting to style the dock:
# When a block is docked the dock attempts to ensure that existing styles for the block are still applied by adding the standard block '''.block_''blockname'''''. Because of this trick we don't need to look at the actual content of a docked item it will always be the same as the block.
# The dock remembers what blocks are docked by saving the user's choices within the database using AJAX calls. This can be looked at to minimise display jumping within a theme's layoutfile. Read on to learn how.
# The dock uses CSS classes to transition the different states. These CSS classes control things such as the whether the dock is visible, whether the panel is visible, and how we know which item is being viewed. Read the section on [[#State_classes|state classes]] to learn more about these.
# The structure of the dock is built entirely by JavaScript. Because of this you will need a tool such as FireBug to inspect it within a page as it won't be there until JavaScript has run.
# Although the base theme doesn't support the dock it does contain some core CSS to structure the dock by default.

So lets get started and look at the structure.
===The structure of the dock===
[[Image:Dock.structure.201005.png|300px|thumb|Dock structure]]
The first image to the left graphically describes the hierarchical structure of the dock. The first thing you will notice about this image is that it doesn't describe what each element is for. It is just to illustrate the html structure without at styles or transformation.

So what are the important elements here?

; div#dock.dock.dock_left_vertical : This is the bar on the left. Positioned by default to be fixed position in the top left hand corner of the screen and 30px wide.
; div.dockeditem_container : This box contains all of the buttons which when clicked or hovered over will display the docked item. Or more technically causing the docked item panel to be shown.
; div#dock_item_x.dockeditem : This represents one of possibly several docked item buttons containing the title of the docked item. There are two things to note about this element: First it is repeated for every docked item. Second the x within the id is the item instance and should not be used for styling.
; div.controls : This contains any special controls for the dock and by default is displayed at the bottom of the dock. As of Moodle 2 Preview Release the only control here is to undock all docked items.
; div#dockeditempanel : This is the panel in which docked items are shown. Although it is within the dock is it positioned outside of the page relative to the button for the item it is currently showing. This element is based loosely off the YUI3 overlay.

===The layout of the dock===
[[Image:Dock.layout.201005.png|300px|thumb|Dock layout]]
The second image on the left shows the layout of these elements within the standard theme.

'''So what has gone on here?'''
First up ignore the bright colours and margins. I have put these colours in simply to highlight everything and ensure there is space between elements so I can show them apart.

; div#dock : So immediately you notice that the dock is in the top left of the screen and the is fixed width. This is achieved by setting a strict with of 30px and setting the position of the ''#dock'' to fixed. The reason that everything is within the one ''#dock'' element is because it makes positioning everything very simple, now that we have set the position of ''#dock'' we don't need to worry about anything other than the panel which we'll get to shortly. You should also note that because of the strict width and position you need to be careful when applying styles to this element as it can have nasty effects on everything else.

; div.dockeditem_container : Next you should notice that the ''.dockeditem_container'' doesn't extend to the bottom of the dock. Because there is not special positioning here it is behaving as div's normally do and this is the perfect place to really start styling your dock.

; div.controls : After that within the structure we have ''div.controls''. This element is positioned absolutely at the bottom of the dock, is 100% wide (so the full width of the dock) and uses ''text-align:center'' to ensure that the controls are centred.

; div.dockeditem : Simply representing a button that can be hovered over or clicked to display the docked item the only important thing to note about this is that you should change the cursor to a pointer so that it is clear you can interact with it.

; div#dockeditempanel : After ''#dock'' this is the most serious element in the dock. This element will contain the docked item and needs to positioned to the left of the dock and at the same height as the title of the item that is being displayed. Luckily you don't need to worry about the top position of the element that will be automatically adjusted by JavaScript however you will need to push the element to the left. This can be done easily by setting the position of the element to relative, and then setting left to 100%. Note you shouldn't style this element unless you know what you are doing, like the main dock element the smallest change can cause some terrible effects.

; div.dockeditempanel_container : This element is there specifically to give you the themer an easy place to start styling the panel.

; div.dockeditempanel_hd : This element contains the title of the docked item plus controls to undock or close it.

; div.dockeditempanel_bd : Contains is the main content area for the panel.

===State classes===
There are several state classes that the dock makes use of to achieve things such as the visibility of the dock, visibility of the panel, and which item is active.
The following table illustrates where these state classes are used.
{| class="nicetable"
! Element
! Class
! Description
! Default CSS
|-
|body
|has_dock
|This class is added to the body element when the dock is visible.
|Margin-left: 30px
|-
|#dock
|nothingdocked
|This class is added to the dock when there is nothing docked.
|visibility: hidden; display: none;
|-
|#dock
|.dock_''position''_''style''
|A special class is added to describe the docks desired position e.g. dock_left_vertical
|
|-
|.dockeditem
|activeitem
|This class is added to the item that is currently being shown.
|Change the background colour
|-
|.dockeditem
|firstdockitem
|This class is added to the first dock item.
|
|-
|.dockeditem h2
|filterrotate
|Added when the title is being rotated by an IE filter [Internet Explorer only]
|
|-
|#dockeditempanel
|dockitempanel_hidden
|Added to the panel when it is not being shown.
|visibility: hidden; display: none;
|-
|#dockeditempanel
|oversized_content
|Added when the panel required scrolling to show everything.
|Set the overflow method
|}

===Layout file changes===
There is only one thing that you need to make sure of within your layout files if you are creating your own. You need to add the class ''block-region'' to all of the block region div's as shown below.
<code php>
<div id="region-post" class="block-region">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
</code>
Whilst there is nothing else you '''need''' to change within your layout files there one other thing that you may want to do.

Because the dock is loaded entirely by JavaScript you will notice a visual jump on the page if all of the blocks within a region have been docked. This is because the dock shrinks sections that have been completely docked so that they don't wast page space.

Within you layout files you can check whether a section has been completely docked and then if it has set the body classes so that it is shrunk when the page is delivered.

I'm going to assume that you have all read the [[Development:Themes 2.0 creating your first theme]]. If you haven't go read it now.
So now that you've created your first theme think back to the code you wrote at the top of your layout files that checks whether a page has block regions pre and post. The code was as follows:
<code php>
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
</code>
Right below these two lines we are going to add two more:
<code php>
$showsidepre = ($hassidepre && !$PAGE->blocks->region_completely_docked('side-pre', $OUTPUT));
$showsidepost = ($hassidepost && !$PAGE->blocks->region_completely_docked('side-post', $OUTPUT));
</code>
What we have here is two variables that tell use whether we should show the block regions pre and post. The verbal interpretation of this string is to say ''We will show this side if this side has content and if there is at least one block that has not been docked.'' and we repeat it for each side.

Now that we know for each region that it has content and that we should show it we need some way to tell the page what block regions to show.
This is achieved by adding special classes to the body element of the page as follows:
; side-pre-only : This gets added to the body if we only want to show the block region pre.
; side-post-only : Just like side-pre-only except for the post region.
; content-only : This gets added if don't want to show either block region.
By default we want to show both regions so we don't need to add any class for this.
So how to do this in PHP?
<code php>
$bodyclasses = array();
if ($showsidepre && !$showsidepost) {
$bodyclasses[] = 'side-pre-only';
} else if ($showsidepost && !$showsidepre) {
$bodyclasses[] = 'side-post-only';
} else if (!$showsidepost && !$showsidepre) {
$bodyclasses[] = 'content-only';
}
</code>
What we have here is three if-else statements, of which either one or none will be true.
# The first if statement says if we want to show the pre region but not the post region add the class ''side-pre-only''
# The second if statement says if we want to show the post region but not the pre region add the class ''side-post-only''
# The third class says if we don't want to display either region add the class ''content-only''

Now that we know which class we want to add to the body element we need to do so. This can be done as follows:
<code php>
<body id="<?php echo $PAGE->bodyid ?>" class="<?php echo $PAGE->bodyclasses.' '.join(' ', $bodyclasses) ?>">
</code>
You'll notice this is very similar to the body tag you wrote in your first theme, however we have added
<code php>
join(' ', $bodyclasses)
</code>
This php command simply concatenates each body class putting a space between each.

Now the final thing to do is make sure that we don't show a block region if we don't have content for it. This can be done by adding if statements around each block region as follows:
<code php>
<?php if ($hassidepre) { ?>
<div id="region-pre" class="block-region">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post" class="block-region">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</code>
For each if statement we are saying ''If this region has content display it.'' You'll notice that here we are using ''$hasside...'' instead of ''$showside...'' this is because we want to add them if they have content even if they won't be shown. Otherwise the dock won't be able to find them and you simply won't see the block.

Having made the above changes if you now look at the layout files for the base theme you start to notice that they are looking very similar and indeed they are. If at any point you get stuck or don't know how to proceed have a look at the base themes layout files and see how its done there.

===The core CSS===
As mentioned in the key points at the start of this document the base theme although not supporting the dock does contain structural CSS that ensure the dock is functional on all themes that choose to support it.
Lets look at the CSS within ''theme/base/style/dock.css'', this is the core structural CSS for the dock.
<code css>
/* Put a margin on the body if the dock is shown */
body.has_dock {margin-left:30px;}
</code>
Well this is very simple, if the dock is being shown apply a 30px margin to the body. This is done to ensure that the dock doesn't overlap the body.

<code css>
/** For the dock itself */
#dock {width:30px;position:fixed;top:0px;left:0px;height:100%;background-color:#FFF;border-right:1px solid #000;z-index:11000;}
#dock.nothingdocked {visibility: hidden;display:none;}
</code>
These two rules style the dock itself. Note the second rule is only applied when nothing is docked in which case we will hide the empty dock.

<code css>
#dock .dockeditem .firstdockitem {margin-top:1em;}
#dock .dockeditem .dockedtitle {border-bottom:1px solid #000;border-top:1px solid #000;cursor:pointer;}
#dock .dockeditem .dockedtitle h2 {font-size:0.8em;line-height:100%;text-align:center;}
#dock .dockeditem .dockedtitle .filterrotate {margin-left:8px;}
</code>
The four rules above style the buttons that will show the docked items. Each docked item has one. The styles being used here arn't doing anything to special other than setting the cursor to pointer so that it is recognised as an actionable element.

<code css>
#dock .controls {position:absolute;bottom:1em;text-align:center;width:100%;}
#dock .controls img {cursor:pointer;}
</code>
Very simply this bit of CSS. It is positioning the controls for the dock at the bottom centre of the dock.

<code css>
/** For the panel the docked blocks are shown in */
#dockeditempanel {min-width:200px;position:relative;z-index:12000;left:100%;}
#dockeditempanel.dockitempanel_hidden {display:none;}
</code>
These two lines are applied to the docked item panel's base element and are VERY important to the operation of the dock. They ensure that when shown the panel is top the left of the dock and that when it is not being displayed it is not visible.

<code css>
#dockeditempanel .dockeditempanel_content {background-color:#fff;border:1px solid #000;z-index:12050;}
#dockeditempanel .dockeditempanel_bd {overflow:auto;width:auto;}
#dockeditempanel .dockeditempanel_bd .block_docked {margin:10px;}
#dockeditempanel .dockeditempanel_hd {border-bottom:1px solid #000;text-align:right;}
#dockeditempanel .dockeditempanel_hd h2 {display:inline;margin:0;padding-right:1em;}
#dockeditempanel .dockeditempanel_hd .commands {display:inline;}
#dockeditempanel .dockeditempanel_hd .commands img {margin-right:2px;vertical-align:middle;}
</code>
The above lines of CSS are used to style the internal content of the panel. Note the styles for the block will be applied as if it were not docked.

And that is it!

Whilst things don't look to difficult when styling things if you don't think carefully about where you are applying styles you can quickly dig yourself a big hole. I would suggest going slowly at first when applying more styles and making sure you don't apply too many styles to the base elements #dock and #dockeditempanel.

==Customising the dock==
This section of the document looks at how to customise the dock using JavaScript.

It was recognised early on during the development of the dock that it probably won't suit everyone's needs, nor would it appeal to everyone. Because of this during development and the frequent revisions that were occurring during Moodle 2.0s development there was always a focus on ensuring the dock was customisable and that someone with a bit of time on their hands and a good knowledge of JavaScript could hack it to bits and make it into the tool they desired.

This document doesn't go into the full details of how to customise the dock but should get anyone keen started quickly. Those who fear JavaScript should leave now!

===Getting started===
The dock is written to make use of YUI3 and all the functionality that it has to offer, the main dock object both looks for specific callback functions and adds manages and fires several important events. At the same time it is also object orientated JavaScript which has the advantage in JavaScript of allowing subsequent JavaScript events to redefine methods of the object.

This allows you the theme designer to write JavaScript to customise the dock in two fashions. The first through events and callbacks. The second through manually overriding the methods the dock uses.

We will look into these two methods in the subsequent sections of this document, for the time being what you need to learn about is the JavaScript structure of the dock.

First all of the code for the dock within Moodle 2.0 is located within the file '''moodle/blocks/dock.js''' and can be viewed online through the CVS repository[http://cvs.moodle.org/moodle/blocks/dock.js?view=markup]

There are three main objects that get used for the dock:
# First up is of course the dock, which is namespaced to M.core_dock.dock. It is instantiated only once per page and is essentially a static object that manages and operates the dock plus everything on it.
# Second is a generic block class. Every block on the page gets instantiated as a generic block unless it has a more specific class (that should extend the generic block class). This generic block class is responsible for moving a block between the dock and its normal block position. It is namespaced to M.core_dock.generic_block.
# The third class is the dock item class which is used to represent an item on the dock. It is responsible for showing the item when required and handles the events that the dock + user trigger. I can hear you asking now why not just add this functionality to the generic block class? because this keeps it open for things other than blocks to be docked.

As well as the above three classes there are some important class objects and properties that you should also be aware of as you may want to work with them when customising the dock.
; M.core_dock.Y : Is a YUI instance for use with the dock.
; M.core_dock.nodes.dock : Is the façade for the dock itself (#dock) and is a YUI3 Node instance.
; M.core_dock.getPanel() : This will return the panel that is used to display docked item within. It is stored locally through M.core_dock.nodes.panel however as it is not initialised until it is required you should always use the getPanel method.

The following are other important notes about the dock that you should read and understand before customising the dock.
# The dock emulates the YUI3 '''on''' method for listening to events. Because the dock requires initialisation which may occur through module dependencies we needed a method of exposing the dock to events prior to initialisation and this is it. It ensures that if you attach events to the dock before it is initialised everything still works fine.
# Both the dock and the item class inherit from Y.EventTarget and publish several events.
# The dock is designed to work both on old and modern browsers and as such there are several places where we branch based on browser and version.
# The generic block class should never be added to for the needs of a single block. Only things that are generic to all blocks should be added to this class. Independent needs should be handled by creating a block specific class that extends the generic block class. The navigation and settings blocks do this currently.

===Extending the dock through events===
Under construction

===Using custom methods for the dock===
Under construction

===Tutorial: Creating a moveable dock===
Under construction

==More information==

* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 how to make the dock horizontal]] - Modifying the dock to make it horizontal.

Development:Styling and customising the dock

2011-03-16T02:55:23Z

Samhemelryk: Added link to horizontal dock tutorial

{{Template:Themes}}{{Moodle 2.0}}The dock is a new addition to Moodle 2.0, it allows the user to move blocks from the flow of the page onto a special bar that is displayed in a constant position on the side of the page by default.
This document looks at how to style the dock using CSS, as well as how to customise or manipulate it within JavaScript.

==Styling the dock==
Styling the dock is really no different to styling anything else within a web site however there are a couple of things that may slow you down and reading the following document may help you in your understanding of how the dock works and how you should go about styling it.

The following items are things that you should be aware of before starting to style the dock:
# When a block is docked the dock attempts to ensure that existing styles for the block are still applied by adding the standard block '''.block_''blockname'''''. Because of this trick we don't need to look at the actual content of a docked item it will always be the same as the block.
# The dock remembers what blocks are docked by saving the user's choices within the database using AJAX calls. This can be looked at to minimise display jumping within a theme's layoutfile. Read on to learn how.
# The dock uses CSS classes to transition the different states. These CSS classes control things such as the whether the dock is visible, whether the panel is visible, and how we know which item is being viewed. Read the section on [[#State_classes|state classes]] to learn more about these.
# The structure of the dock is built entirely by JavaScript. Because of this you will need a tool such as FireBug to inspect it within a page as it won't be there until JavaScript has run.
# Although the base theme doesn't support the dock it does contain some core CSS to structure the dock by default.

So lets get started and look at the structure.
===The structure of the dock===
[[Image:Dock.structure.201005.png|300px|thumb|Dock structure]]
The first image to the left graphically describes the hierarchical structure of the dock. The first thing you will notice about this image is that it doesn't describe what each element is for. It is just to illustrate the html structure without at styles or transformation.

So what are the important elements here?

; div#dock.dock.dock_left_vertical : This is the bar on the left. Positioned by default to be fixed position in the top left hand corner of the screen and 30px wide.
; div.dockeditem_container : This box contains all of the buttons which when clicked or hovered over will display the docked item. Or more technically causing the docked item panel to be shown.
; div#dock_item_x.dockeditem : This represents one of possibly several docked item buttons containing the title of the docked item. There are two things to note about this element: First it is repeated for every docked item. Second the x within the id is the item instance and should not be used for styling.
; div.controls : This contains any special controls for the dock and by default is displayed at the bottom of the dock. As of Moodle 2 Preview Release the only control here is to undock all docked items.
; div#dockeditempanel : This is the panel in which docked items are shown. Although it is within the dock is it positioned outside of the page relative to the button for the item it is currently showing. This element is based loosely off the YUI3 overlay.

===The layout of the dock===
[[Image:Dock.layout.201005.png|300px|thumb|Dock layout]]
The second image on the left shows the layout of these elements within the standard theme.

'''So what has gone on here?'''
First up ignore the bright colours and margins. I have put these colours in simply to highlight everything and ensure there is space between elements so I can show them apart.

; div#dock : So immediately you notice that the dock is in the top left of the screen and the is fixed width. This is achieved by setting a strict with of 30px and setting the position of the ''#dock'' to fixed. The reason that everything is within the one ''#dock'' element is because it makes positioning everything very simple, now that we have set the position of ''#dock'' we don't need to worry about anything other than the panel which we'll get to shortly. You should also note that because of the strict width and position you need to be careful when applying styles to this element as it can have nasty effects on everything else.

; div.dockeditem_container : Next you should notice that the ''.dockeditem_container'' doesn't extend to the bottom of the dock. Because there is not special positioning here it is behaving as div's normally do and this is the perfect place to really start styling your dock.

; div.controls : After that within the structure we have ''div.controls''. This element is positioned absolutely at the bottom of the dock, is 100% wide (so the full width of the dock) and uses ''text-align:center'' to ensure that the controls are centred.

; div.dockeditem : Simply representing a button that can be hovered over or clicked to display the docked item the only important thing to note about this is that you should change the cursor to a pointer so that it is clear you can interact with it.

; div#dockeditempanel : After ''#dock'' this is the most serious element in the dock. This element will contain the docked item and needs to positioned to the left of the dock and at the same height as the title of the item that is being displayed. Luckily you don't need to worry about the top position of the element that will be automatically adjusted by JavaScript however you will need to push the element to the left. This can be done easily by setting the position of the element to relative, and then setting left to 100%. Note you shouldn't style this element unless you know what you are doing, like the main dock element the smallest change can cause some terrible effects.

; div.dockeditempanel_container : This element is there specifically to give you the themer an easy place to start styling the panel.

; div.dockeditempanel_hd : This element contains the title of the docked item plus controls to undock or close it.

; div.dockeditempanel_bd : Contains is the main content area for the panel.

===State classes===
There are several state classes that the dock makes use of to achieve things such as the visibility of the dock, visibility of the panel, and which item is active.
The following table illustrates where these state classes are used.
{| class="nicetable"
! Element
! Class
! Description
! Default CSS
|-
|body
|has_dock
|This class is added to the body element when the dock is visible.
|Margin-left: 30px
|-
|#dock
|nothingdocked
|This class is added to the dock when there is nothing docked.
|visibility: hidden; display: none;
|-
|#dock
|.dock_''position''_''style''
|A special class is added to describe the docks desired position e.g. dock_left_vertical
|
|-
|.dockeditem
|activeitem
|This class is added to the item that is currently being shown.
|Change the background colour
|-
|.dockeditem
|firstdockitem
|This class is added to the first dock item.
|
|-
|.dockeditem h2
|filterrotate
|Added when the title is being rotated by an IE filter [Internet Explorer only]
|
|-
|#dockeditempanel
|dockitempanel_hidden
|Added to the panel when it is not being shown.
|visibility: hidden; display: none;
|-
|#dockeditempanel
|oversized_content
|Added when the panel required scrolling to show everything.
|Set the overflow method
|}

===Layout file changes===
There is only one thing that you need to make sure of within your layout files if you are creating your own. You need to add the class ''block-region'' to all of the block region div's as shown below.
<code php>
<div id="region-post" class="block-region">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
</code>
Whilst there is nothing else you '''need''' to change within your layout files there one other thing that you may want to do.

Because the dock is loaded entirely by JavaScript you will notice a visual jump on the page if all of the blocks within a region have been docked. This is because the dock shrinks sections that have been completely docked so that they don't wast page space.

Within you layout files you can check whether a section has been completely docked and then if it has set the body classes so that it is shrunk when the page is delivered.

I'm going to assume that you have all read the [[Development:Themes 2.0 creating your first theme]]. If you haven't go read it now.
So now that you've created your first theme think back to the code you wrote at the top of your layout files that checks whether a page has block regions pre and post. The code was as follows:
<code php>
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
</code>
Right below these two lines we are going to add two more:
<code php>
$showsidepre = ($hassidepre && !$PAGE->blocks->region_completely_docked('side-pre', $OUTPUT));
$showsidepost = ($hassidepost && !$PAGE->blocks->region_completely_docked('side-post', $OUTPUT));
</code>
What we have here is two variables that tell use whether we should show the block regions pre and post. The verbal interpretation of this string is to say ''We will show this side if this side has content and if there is at least one block that has not been docked.'' and we repeat it for each side.

Now that we know for each region that it has content and that we should show it we need some way to tell the page what block regions to show.
This is achieved by adding special classes to the body element of the page as follows:
; side-pre-only : This gets added to the body if we only want to show the block region pre.
; side-post-only : Just like side-pre-only except for the post region.
; content-only : This gets added if don't want to show either block region.
By default we want to show both regions so we don't need to add any class for this.
So how to do this in PHP?
<code php>
$bodyclasses = array();
if ($showsidepre && !$showsidepost) {
$bodyclasses[] = 'side-pre-only';
} else if ($showsidepost && !$showsidepre) {
$bodyclasses[] = 'side-post-only';
} else if (!$showsidepost && !$showsidepre) {
$bodyclasses[] = 'content-only';
}
</code>
What we have here is three if-else statements, of which either one or none will be true.
# The first if statement says if we want to show the pre region but not the post region add the class ''side-pre-only''
# The second if statement says if we want to show the post region but not the pre region add the class ''side-post-only''
# The third class says if we don't want to display either region add the class ''content-only''

Now that we know which class we want to add to the body element we need to do so. This can be done as follows:
<code php>
<body id="<?php echo $PAGE->bodyid ?>" class="<?php echo $PAGE->bodyclasses.' '.join(' ', $bodyclasses) ?>">
</code>
You'll notice this is very similar to the body tag you wrote in your first theme, however we have added
<code php>
join(' ', $bodyclasses)
</code>
This php command simply concatenates each body class putting a space between each.

Now the final thing to do is make sure that we don't show a block region if we don't have content for it. This can be done by adding if statements around each block region as follows:
<code php>
<?php if ($hassidepre) { ?>
<div id="region-pre" class="block-region">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post" class="block-region">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</code>
For each if statement we are saying ''If this region has content display it.'' You'll notice that here we are using ''$hasside...'' instead of ''$showside...'' this is because we want to add them if they have content even if they won't be shown. Otherwise the dock won't be able to find them and you simply won't see the block.

Having made the above changes if you now look at the layout files for the base theme you start to notice that they are looking very similar and indeed they are. If at any point you get stuck or don't know how to proceed have a look at the base themes layout files and see how its done there.

===The core CSS===
As mentioned in the key points at the start of this document the base theme although not supporting the dock does contain structural CSS that ensure the dock is functional on all themes that choose to support it.
Lets look at the CSS within ''theme/base/style/dock.css'', this is the core structural CSS for the dock.
<code css>
/* Put a margin on the body if the dock is shown */
body.has_dock {margin-left:30px;}
</code>
Well this is very simple, if the dock is being shown apply a 30px margin to the body. This is done to ensure that the dock doesn't overlap the body.

<code css>
/** For the dock itself */
#dock {width:30px;position:fixed;top:0px;left:0px;height:100%;background-color:#FFF;border-right:1px solid #000;z-index:11000;}
#dock.nothingdocked {visibility: hidden;display:none;}
</code>
These two rules style the dock itself. Note the second rule is only applied when nothing is docked in which case we will hide the empty dock.

<code css>
#dock .dockeditem .firstdockitem {margin-top:1em;}
#dock .dockeditem .dockedtitle {border-bottom:1px solid #000;border-top:1px solid #000;cursor:pointer;}
#dock .dockeditem .dockedtitle h2 {font-size:0.8em;line-height:100%;text-align:center;}
#dock .dockeditem .dockedtitle .filterrotate {margin-left:8px;}
</code>
The four rules above style the buttons that will show the docked items. Each docked item has one. The styles being used here arn't doing anything to special other than setting the cursor to pointer so that it is recognised as an actionable element.

<code css>
#dock .controls {position:absolute;bottom:1em;text-align:center;width:100%;}
#dock .controls img {cursor:pointer;}
</code>
Very simply this bit of CSS. It is positioning the controls for the dock at the bottom centre of the dock.

<code css>
/** For the panel the docked blocks are shown in */
#dockeditempanel {min-width:200px;position:relative;z-index:12000;left:100%;}
#dockeditempanel.dockitempanel_hidden {display:none;}
</code>
These two lines are applied to the docked item panel's base element and are VERY important to the operation of the dock. They ensure that when shown the panel is top the left of the dock and that when it is not being displayed it is not visible.

<code css>
#dockeditempanel .dockeditempanel_content {background-color:#fff;border:1px solid #000;z-index:12050;}
#dockeditempanel .dockeditempanel_bd {overflow:auto;width:auto;}
#dockeditempanel .dockeditempanel_bd .block_docked {margin:10px;}
#dockeditempanel .dockeditempanel_hd {border-bottom:1px solid #000;text-align:right;}
#dockeditempanel .dockeditempanel_hd h2 {display:inline;margin:0;padding-right:1em;}
#dockeditempanel .dockeditempanel_hd .commands {display:inline;}
#dockeditempanel .dockeditempanel_hd .commands img {margin-right:2px;vertical-align:middle;}
</code>
The above lines of CSS are used to style the internal content of the panel. Note the styles for the block will be applied as if it were not docked.

And that is it!

Whilst things don't look to difficult when styling things if you don't think carefully about where you are applying styles you can quickly dig yourself a big hole. I would suggest going slowly at first when applying more styles and making sure you don't apply too many styles to the base elements #dock and #dockeditempanel.

==Customising the dock==
This section of the document looks at how to customise the dock using JavaScript.

It was recognised early on during the development of the dock that it probably won't suit everyone's needs, nor would it appeal to everyone. Because of this during development and the frequent revisions that were occurring during Moodle 2.0s development there was always a focus on ensuring the dock was customisable and that someone with a bit of time on their hands and a good knowledge of JavaScript could hack it to bits and make it into the tool they desired.

This document doesn't go into the full details of how to customise the dock but should get anyone keen started quickly. Those who fear JavaScript should leave now!

===Getting started===
The dock is written to make use of YUI3 and all the functionality that it has to offer, the main dock object both looks for specific callback functions and adds manages and fires several important events. At the same time it is also object orientated JavaScript which has the advantage in JavaScript of allowing subsequent JavaScript events to redefine methods of the object.

This allows you the theme designer to write JavaScript to customise the dock in two fashions. The first through events and callbacks. The second through manually overriding the methods the dock uses.

We will look into these two methods in the subsequent sections of this document, for the time being what you need to learn about is the JavaScript structure of the dock.

First all of the code for the dock within Moodle 2.0 is located within the file '''moodle/blocks/dock.js''' and can be viewed online through the CVS repository[http://cvs.moodle.org/moodle/blocks/dock.js?view=markup]

There are three main objects that get used for the dock:
# First up is of course the dock, which is namespaced to M.core_dock.dock. It is instantiated only once per page and is essentially a static object that manages and operates the dock plus everything on it.
# Second is a generic block class. Every block on the page gets instantiated as a generic block unless it has a more specific class (that should extend the generic block class). This generic block class is responsible for moving a block between the dock and its normal block position. It is namespaced to M.core_dock.generic_block.
# The third class is the dock item class which is used to represent an item on the dock. It is responsible for showing the item when required and handles the events that the dock + user trigger. I can hear you asking now why not just add this functionality to the generic block class? because this keeps it open for things other than blocks to be docked.

As well as the above three classes there are some important class objects and properties that you should also be aware of as you may want to work with them when customising the dock.
; M.core_dock.Y : Is a YUI instance for use with the dock.
; M.core_dock.nodes.dock : Is the façade for the dock itself (#dock) and is a YUI3 Node instance.
; M.core_dock.getPanel() : This will return the panel that is used to display docked item within. It is stored locally through M.core_dock.nodes.panel however as it is not initialised until it is required you should always use the getPanel method.

The following are other important notes about the dock that you should read and understand before customising the dock.
# The dock emulates the YUI3 '''on''' method for listening to events. Because the dock requires initialisation which may occur through module dependencies we needed a method of exposing the dock to events prior to initialisation and this is it. It ensures that if you attach events to the dock before it is initialised everything still works fine.
# Both the dock and the item class inherit from Y.EventTarget and publish several events.
# The dock is designed to work both on old and modern browsers and as such there are several places where we branch based on browser and version.
# The generic block class should never be added to for the needs of a single block. Only things that are generic to all blocks should be added to this class. Independent needs should be handled by creating a block specific class that extends the generic block class. The navigation and settings blocks do this currently.

===Extending the dock through events===
Under construction

===Using custom methods for the dock===
Under construction

===Tutorial: Creating a moveable dock===
Under construction

==More information==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Styling and customising the dock]] - How to style and customise the dock.

Development:Themes 2.0

2011-03-16T02:54:37Z

Samhemelryk: Added link to horizontal dock tutorial

{{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 echo $PAGE->bodyid ?>" class="<?php echo $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 echo $PAGE->bodyid; ?>" class="<?php echo $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>
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: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]]

Development:Themes 2.0 how to make the dock horizontal

2011-03-16T02:53:07Z

Samhemelryk: Intial creation of tutorial

This quick tutorial looks at how to move the dock from its vertical position on the left hand side of the screen to a horizontal position at the top of the screen.<br />
This modification will be done entirely within a theme through the creation of a small amount of JavaScript and a few lines of CSS.

==Getting started==

If you're new to Moodle and haven't yet read the tutorial on creating your first theme I strongly suggest you head there first.<br />
I'd also strongly suggest you read [[Development:Styling and customising the dock]] which explains the structure of the dock and a few of the things you will need to know in order to tackle this tutorial.

In order to make this tutorial easier to understand I am going to create a new theme that we'll call '''dockmod''' in which we will create this modification.
So first step within your Moodle theme directory create a new directory called ''dockmod''. Within this new directory we'll create two further directories JavaScript, and style.
You should now have a directory structure like the one shown below:
<pre>
moodle/theme/dockmod
moodle/theme/dockmod/javascript
moodle/theme/dockmod/style
</pre>

The next step is to create the three files we are going to need, config.php, dockmod.js, and dockmod.css.
# config.php is of course for our theme's configuration and as you know an essential for any theme.
# dockmod.js will be created in the JavaScript directory, this file will contain the bit of JavaScript we need to write to get our modification to work.
# dockmod.css will be created in the style directory, this file will contain the CSS we need in order to make the dock horizontal.

You should end up with the following files:
<pre>
moodle/theme/dockmod/config.php
moodle/theme/dockmod/javascript/dockmod.js
moodle/theme/dockmod/style/dockmod.css
</pre>

==config.php==
In this step we will be setting up the config.php file for this theme, to be truthful there should be nothing new here for you, this is the easy part of the tutorial.
The idea of this theme is to simply extend the standard theme and make the dock modification. This has the advantage that our theme will only consist of the JS and CSS required to achieve the dock modification we want.

So open the config.php file in your favourite editor and type the following in:
<code php>
<?php

/**
* This is the config file for the dockmod theme.
*/

$THEME->name = 'dockmod';
$THEME->sheets = array('dockmod');
$THEME->parents = array('standard', 'base');
$THEME->enable_dock = true;
$THEME->javascripts = array('dockmod');
</code>

So pretty simple really, the name of our theme is ''dockmod'', you already knew that!
The parents for this new theme are standard and base as explained above.
We have one stylesheet also called dockmod (theme/dockmod/style/dockmod.css), and we have one JavaScript file also called dockmod (theme/dockmod/javascript/dockmod.js) and of course its essential we enable the dock, otherwise there's no point in creating this modification.

==The JavaScript==
OK this is where the tutorial starts to enter the [potentially] unknown.

The dock is pretty cool in that it looks for a specific JavaScript function when it loads and calls it if it exists, we can use this to modify the dock as we want. It also published several events that we are able to listen to in order to make further modifications when certain things happen.

In our case we want to make the dock horizontal. Now this isn't actually as nasty as it sounds because in a limited way the dock supports this! When I first wrote the dock I had in mind that one day I would have time to extend the dock to make it moveable, as such I wrote some basic support into it to allow the position and orientation to be switched. I know that a few of you in the community who have looked at making a horizontal dock have found these properties. Functions that rely on the position or orientation of the dock such as making the titles vertical have code within them that checks it makes sense to do so based upon the values of those properties.
All in all this makes our modification a lot simpler as half the work is already done!

To start with open ''javascript/dockmod.js'' in your favourite editor and type the following:
<code javascript>
function customise_dock_for_theme() {
var dock = M.core_dock;
dock.cfg.position = 'top';
dock.cfg.orientation = 'horizontal';
}
</code>

And that is it; It sounds hard, but as you see really it is very easy (although as you get through this tutorial you will see we actually add a bit more JS later on).

So how this works:
<code javascript>
function customise_dock_for_theme() { .... }
</code>
As mentioned above when the dock first loads it looks for a function and calls it, well this is the function '''customise_dock_for_theme'''.

<code javascript>
var dock = M.core_dock;
</code>
Here we are collecting the dock into a variable. It is in this case available from the global M object.

<code javascript>
dock.cfg.position = 'top';
dock.cfg.orientation = 'horizontal';
</code>
These two lines set two configuration variables for the dock, the position and the orientation. There are several other config properties that perhaps will be explored within another document or tutorial.

==The CSS==
If you save you changes presently and view your theme in your browser you will likely see a big mess. That is because while the JavaScript supports a horizontal dock there is not yet any CSS to support displaying the dock horizontally.

Because of this we will need to write a bit of CSS to ensure the dock is displayed correctly.
Open ''style/dockmod.css'' in your favourite editor and type the following:
<code css>
body.has_dock {margin-top:30px;margin-left:0;}
body.has_dock_top_horizontal #dock {width:100%;height:30px;background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;border-right-width:0;border-bottom:1px solid #000;}
body.has_dock_top_horizontal #dock .dockeditem_container {margin-top:0;}
body.has_dock_top_horizontal #dock .dockeditem {display:inline-block;}
body.has_dock_top_horizontal #dock .dockeditem .dockedtitle {background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;background-position:0 10%;border-style:solid;border-width: 0 1px 0 0;border-color:#AAA;}
body.has_dock_top_horizontal #dock .dockeditem .dockedtitle h2 {margin:0 12px;line-height:30px;}
body.has_dock_top_horizontal #dock .dockeditem.firstdockitem {margin-left:10px;}
body.has_dock_top_horizontal #dock .dockeditem.firstdockitem .dockedtitle {border-left-width:1px;}
body.has_dock_top_horizontal #dock .controls {bottom:auto;right:10px;top:0;width:auto;line-height:30px;}
body.has_dock_top_horizontal #dock #dockeditempanel {position:absolute;}
</code>

That's it!

The first line of CSS is to correct the margin on the body that accommodates the dock, we need to remove the left margin and increase the top margin.
The other lines of CSS basically just correct change to horizontal images, change positioning from vertical to horizontal, and swap X/Y properties.

==Correcting a vertical bug==
If you now open your site in your browser and switch to your theme you should see a horizontal dock.
If you have a bit of a play with if you will notice that if you dock the settings block and fully expand it it will run off the bottom of the page and there will be no scroll bar.
This has happened because we changed the position attributes of the dock in our CSS above. Essentially we could tinker with the CSS and try to fix it there, however based upon the design of the block and the complexities of getting it to work cross browser I can tell you it's going to be hard. Instead I'll show you how we can fix it in JavaScript.

Open your dockmod.js file again and type the following within the customize dock function below the three lines that are already in there.
<code javascript>
dock.on('dock:resizepanelcomplete', theme_dockmod_handle_resize);
</code>

This line of code is adding an event listener to the dock so that when it fires the '''dock:resizepanelcomplete''' event the function '''theme_dockmod_handle_resize''' which we create shortly will get called.

The ''resizepanelcomplete'' function gets called '''after''' the panel that shows the content of a block has been resized. The panel gets resized any time it's display changes, e.g. when it is shown, or when the content within the panel changes (you expand something).<br />
This event is perfect for our needs as when it is called we can look at the height of the panel and if it is more than the height of the screen we can add scrollbars to it and set the height so that the user can access all of the content of the panel.

Now we need to write the ''theme_dockmod_handle_resize'' function. Below the customize dock function type the following:
<code javascript>
function theme_dockmod_handle_resize() {
var dock = M.core_dock;
var panel = dock.getPanel();
var item = dock.getActiveItem();
// Check its visible no point doing anything if its not.
if (panel.visible === false || typeof(item) !== 'object') {
return;
}
var buffer = dock.cfg.buffer;
var screenheight = parseInt(dock.nodes.body.get('winHeight'))-(buffer*2)-dock.nodes.dock.get('offsetHeight');
var scrolltop = panel.contentBody.get('scrollTop');
// Reset the height of the panel so that we can accurately measure it
panel.contentBody.setStyle('height', 'auto');
// Remove the oversized class if it is there.
panel.removeClass('oversized_content');
var panelheight = panel.get('offsetHeight');
// Set the height of the panel if required and add the oversized class
if (panelheight > screenheight) {
panel.contentBody.setStyle('height', (screenheight - panel.contentHeader.get('offsetHeight'))+'px');
panel.addClass('oversized_content');
}
// Set the scrolltop of the panel to what it was before we started.
if (scrolltop) {
panel.contentBody.set('scrollTop', scrolltop);
}
}
</code>

Save the file now, purge the Moodle cache, and reload the page.
If you try to replicate the bug now you should find instead you get scrollbars and things work fine.

Congratulations, you've successfully created a horizontal dock!

==Complete source==
The following is the complete source files for this tutorial.
===config.php===
<code php>
<?php

/**
* This is the config file for the dockmod theme.
*/

$THEME->name = 'dockmod';
$THEME->sheets = array('dockmod');
$THEME->parents = array('standard', 'base');
$THEME->enable_dock = true;
$THEME->javascripts = array('dockmod');
</code>

===dockmod.css===
<code css>
body.has_dock {margin-top:30px;margin-left:0;}

/** This is the CSS to display the block on the top of the screen */
.has_dock_top_horizontal #dock {width:100%;height:30px;background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;border-right-width:0;border-bottom:1px solid #000;}
.has_dock_top_horizontal #dock .dockeditem_container {margin-top:0;}
.has_dock_top_horizontal #dock .dockeditem {display:inline-block;}
.has_dock_top_horizontal #dock .dockeditem .dockedtitle {background-image:url([[pix:theme|hgradient]]);background-repeat: repeat-x;background-position:0 10%;border-style:solid;border-width: 0 1px 0 0;border-color:#AAA;}
.has_dock_top_horizontal #dock .dockeditem .dockedtitle h2 {margin:0 12px;line-height:30px;}
.has_dock_top_horizontal #dock .dockeditem.firstdockitem {margin-left:10px;}
.has_dock_top_horizontal #dock .dockeditem.firstdockitem .dockedtitle {border-left-width:1px;}
.has_dock_top_horizontal #dock .controls {bottom:auto;right:10px;top:0;width:auto;line-height:30px;}
.has_dock_top_horizontal #dock #dockeditempanel {position:absolute;}
</code>

===dockmod.js===
<code javascript>
function theme_dockmod_handle_resize() {
var dock = M.core_dock;
var panel = dock.getPanel();
var item = dock.getActiveItem();
// Check its visible no point doing anything if its not.
if (panel.visible === false || typeof(item) !== 'object') {
return;
}
var buffer = dock.cfg.buffer;
var screenheight = parseInt(dock.nodes.body.get('winHeight'))-(buffer*2)-dock.nodes.dock.get('offsetHeight');
var scrolltop = panel.contentBody.get('scrollTop');
// Reset the height of the panel so that we can accurately measure it
panel.contentBody.setStyle('height', 'auto');
// Remove the oversized class if it is there.
panel.removeClass('oversized_content');
var panelheight = panel.get('offsetHeight');
// Set the height of the panel if required and add the oversized class
if (panelheight > screenheight) {
panel.contentBody.setStyle('height', (screenheight - panel.contentHeader.get('offsetHeight'))+'px');
panel.addClass('oversized_content');
}
// Set the scrolltop of the panel to what it was before we started.
if (scrolltop) {
panel.contentBody.set('scrollTop', scrolltop);
}
}
</code>

==Creating a moveable dock==
A while ago I created theme that like this one supports a horizontal dock, however it goes one step further by adding a button above the undock all button that when clicked moves the down to the next position (without refreshing the page).

For those interested in having a look at that you can find it on my github account at: https://github.com/samhemelryk/moodle-theme_dockmod

==More information==

* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Styling and customising the dock]]