Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Adding courses and categories to the custom menu

From MoodleDocs

Hello this is going to be a very brief tutorial on how to add a courses and categories tree to the custom menu.
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.

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.

<?php

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

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 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: class theme_coursecategorymenu_core_renderer extends core_renderer {

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

}

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:

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);

So lets work through this code line by line:

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

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.

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

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

$categorytree = get_course_category_tree();

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.

$categorytree = get_course_category_tree(); foreach ($categorytree as $category) {

   $this->add_category_to_custommenu($branch, $category);

}

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

return parent::render_custom_menu($menu);

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

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);
       }
   }

}

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.

protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {

   .....

}

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.

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

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.

if (!empty($category->categories)) {

   foreach ($category->categories as $subcategory) {
       $this->add_category_to_custommenu($branch, $subcategory);
   }

}

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.
This is called recursion.

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);
   }

} This code is very similar to the above code except that we are looking at the courses within this category.
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:

<?php

$string['courses'] = 'Courses';

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

<?php

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

renderers.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);
           }
       }
   }

}

lang/en/theme_coursecategorymenu.php

<?php

$string['courses'] = 'Courses';

See also