Development:Navigation 2.0 navbar proposal: Difference between revisions

Revision as of 06:14, 13 July 2009

Navigation Bar in Moodle 2.0

Currently I am aiding Tim and his mega-development effort by looking into what can be done with the navigation bar in Moodle 2.0. The end desire is that build_navigation() is deprecated and replaced by a new OO navbar.

We would obviously like this new navbar to be self responsible whilst still being flexible enough that you can add to it as you need to.

The following is my current thinking on this topic and I would love to know your thoughts on the matter, as well as any changes or work-overs you can spot.

The Plan

As suggested in Development:Navigation 2.0 the navbar object will be made available through $OUTPUT->navbar, both for output and interaction. It will be set up to generate as much of the navbar as it possibly can without any input, and allow the developer to add items to the navbar as they wish.

By default the navigation bar will generate the following items (depending on what is available):

Site's short name
Course categories (1..n)
Course short name
Module plural (e.g. forums, SCORMs/AICCs)
Module's name

Also worth noting is that when looking at the structure of a Moodle course it made more sense to me that rather than adding an item for the modules plural name, an item should be added for the course section (e.g. week 1, week 2, week 3) however as there is no page specifically for the course section this is not possible. I will however comment an appropriate point for which this could be modified should this ever be an option.

Internal Operation

The navbar object will be initialised by $PAGE at the same time that theme and output are initialised (PAGE::initialise_theme_and_output) by calling an internal method of navbar $this->_navbar = navbar::load(); The load function for navbar will then proceed to investigate the PAGE object in order to work out what it can automatically build. In order to aid the navbar in its auto-generation the following functions should be called if appropriate. $PAGE->set_cm($cm); $PAGE->set_course($course); $PAGE->set_category_by_id($id); It is essential that any of the applicable functions above are called before the navigation is interacted with.

Generation of navbar items will be undertaken by one or more of the following three internal functions depending on what level of information is available. navbar::generate_for_category($category); // Called if cm, course, and/or category have been set navbar::generate_for_course($course); // Called if cm or course have been set navbar::generate_for_cm($cm); // Called only if cm has been set Each of the functions will add items for its approriate object (cm, course, category) to the item stack. When the navbar output function is called any items that the user has added will be added to the end of the item stack, and then the navbar HTML will be generated.

Interaction

When developing code for Moodle the following methods can be used to interact with the navbar. $OUTPUT->navbar->add(title, url, type[optional]); // Add a new navbar item

Implementation

The plan is to deprecate build_navigation and would be done using the above planned code in the following manner.

Replace: $navlinks = array(); if (has_capability('moodle/course:viewparticipants', get_context_instance(CONTEXT_COURSE, $course->id)) || has_capability('moodle/site:viewparticipants', $syscontext)) {

   $navlinks[] = array('name' => $strparticipants, 'link' => "$CFG->wwwroot/user/index.php?id=$course->id", 'type' => 'core');

} $navlinks[] = array('name' => $fullname, 'link' => "$CFG->wwwroot/user/view.php?id=$user->id&course=$course->id", 'type' => 'title'); $navlinks[] = array('name' => $strforumposts, 'link' => , 'type' => 'title'); $navlinks[] = array('name' => $strmode, 'link' => , 'type' => 'title'); $navigation = build_navigation($navlinks); print_header("$course->shortname: $fullname: $strmode", $course->fullname,$navigation);

With: if (has_capability('moodle/course:viewparticipants', get_context_instance(CONTEXT_COURSE, $course->id)) || has_capability('moodle/site:viewparticipants', $syscontext)) {

   $OUTPUT->navbar->add($strparticipants, $CFG->wwwroot.'/user/index.php?id='.$course->id);

} $OUTPUT->navbar->add($strforumposts); $OUTPUT->navbar->add($strmode); $PAGE->set_heading($course->fullname); echo $OUTPUT->header();

In the template: if ($navigation) { // This is the navigation bar with breadcrumbs ?>


        <?php print_navigation($navigation); ?>

Will be replaced by <?php if ($OUTPUT->navbar()) { // This is the navigation bar with breadcrumbs ?>


        <?php echo $OUTPUT->navbar(); ?>

Further Information

Development:Navigation_2.0

Development:Navigation 2.0 implementation plan

@@ Line 4: / Line 4: @@
 The end desire is that ''build_navigation()'' is deprecated and replaced by a new OO navbar.
-We would obviously like this new navbar to be self responsible whilst still being flexible enough that you can interact and modify it as you wish.
+We would obviously like this new navbar to be self responsible whilst still being flexible enough that you can add to it as you need to.
 The following is my current thinking on this topic and I would love to know your thoughts on the matter, as well as any changes or work-overs you can spot.
 ===The Plan===
-As suggested in Development:Navigation 2.0 the navbar object will be made available through $OUTPUT->navbar, both for output and interaction.
+As suggested in [[Development:Navigation 2.0]] the navbar object will be made available through $OUTPUT->navbar, both for output and interaction.
-It will be set up to generate as much of the navbar as it possibly can without any input, and with sufficient methods to allow you to add, edit, and remove items registered in the navbar.
+It will be set up to generate as much of the navbar as it possibly can without any input, and allow the developer to add items to the navbar as they wish.
-By default the navigation bar will generate the following items:
+By default the navigation bar will generate the following items (depending on what is available):
 * Site's short name
 * Course categories (1..n)
 * Course short name
+* Module plural (e.g. forums, SCORMs/AICCs)
+* Module's name
+Also worth noting is that when looking at the structure of a Moodle course it made more sense to me that rather than adding an item for the modules plural name, an item should be added for the course section (e.g. week 1, week 2, week 3) however as there is no page specifically for the course section this is not possible. I will however comment an appropriate point for which this could be modified should this ever be an option.
-If you pass the navbar a module as well by calling
+===Internal Operation===
+The navbar object will be initialised by $PAGE at the same time that theme and output are initialised (PAGE::initialise_theme_and_output) by calling an internal method of navbar
 <code php>
-navbar->add_module($cm);
+$this->_navbar = navbar::load();
 </code>
-then it will also generate:
+The load function for navbar will then proceed to investigate the PAGE object in order to work out what it can automatically build.
-* Module plural (e.g. forums, SCORMs/AICCs)
+In order to aid the navbar in its auto-generation the following functions should be called if appropriate.
-* Module's name
+<code php>
+$PAGE->set_cm($cm);
+$PAGE->set_course($course);
+$PAGE->set_category_by_id($id);
+</code>
+It is essential that any of the applicable functions above are called before the navigation is interacted with.
-When interacting with the navbar items you will be able to access them by calling the get method with the navbar items title. However this relies on you knowing the title of the navbar item you are after, something which you may not always know. Because of this when each navbar item is generated it will be given a type that matches what it is (e.g. course, coursecategory, module) and the coder can call get_by_type(my_type) to fetch an array of navbar items that match type specified.
+Generation of navbar items will be undertaken by one or more of the following three internal functions depending on what level of information is available.
+<code php>
-Also worth noting is that to me when looking at the structure of a Moodle course it made more sense to me that rather than adding an item for the modules plural name, an item should be added for the course section (e.g. week 1, week 2, week 3) however as there is no page specifically for the course section this is not possible. I will however comment an appropriate point for which this could be modified should this ever be an option.
+navbar::generate_for_category($category); // Called if cm, course, and/or category have been set
+navbar::generate_for_course($course); // Called if cm or course have been set
+navbar::generate_for_cm($cm); // Called only if cm has been set
+</code>
+Each of the functions will add items for its approriate object (cm, course, category) to the item stack.
+When the navbar output function is called any items that the user has added will be added to the end of the item stack, and then the navbar HTML will be generated.
 ===Interaction===
 When developing code for Moodle the following methods can be used to interact with the navbar.
 <code php>
-$OUTPUT->navbar->add_module(course_module); // Pass a module to the navbar to generate items for
+$OUTPUT->navbar->add(title, url, type[optional]); // Add a new navbar item
-$OUTPUT->navbar->add(title, url, type[optional:default=custom]); // Add a new navbar item
-$OUTPUT->navbar->exists(title); // Checks if a navbar item with a given title exists
-$OUTPUT->navbar->get(title) // Returns a single navbar item
-$OUTPUT->navbar->get_by_type(type); // Returns an array of navbar items that match the type specified
-$OUTPUT->navbar->remove(title); // Removes a navbar item
-</code>
-Editing navbar items
-<code php>
-$OUTPUT->navbar->get(title)->title = 'newtitle';
-$OUTPUT->navbar->get(title)->url = 'newtitle';
-$OUTPUT->navbar->get(title)->icon = 'newtitle';
-$OUTPUT->navbar->get(title)->elementid = 'newid';
-$OUTPUT->navbar->get(title)->add_css_class('newclass');
 </code>
 ===Implementation===
 The plan is to deprecate build_navigation and would be done using the above planned code in the following manner.
@@ Line 53: / Line 56: @@
 <code php>
 $navlinks = array();
-$navlinks[] = array('name' => $strcategories, 'link' => 'index.php', 'type' => 'misc');
+if (has_capability('moodle/course:viewparticipants', get_context_instance(CONTEXT_COURSE, $course->id)) || has_capability('moodle/site:viewparticipants', $syscontext)) {
-$navlinks[] = array('name' => format_string($category->name), 'link' => null, 'type' => 'misc');
+    $navlinks[] = array('name' => $strparticipants, 'link' => "$CFG->wwwroot/user/index.php?id=$course->id", 'type' => 'core');
+}
+$navlinks[] = array('name' => $fullname, 'link' => "$CFG->wwwroot/user/view.php?id=$user->id&amp;course=$course->id", 'type' => 'title');
+$navlinks[] = array('name' => $strforumposts, 'link' => '', 'type' => 'title');
+$navlinks[] = array('name' => $strmode, 'link' => '', 'type' => 'title');
 $navigation = build_navigation($navlinks);
-print_header("$site->shortname: $category->name", "$site->fullname: $strcourses", $navigation, '', '', true, $navbaritem);
+print_header("$course->shortname: $fullname: $strmode", $course->fullname,$navigation);
 </code>
 With:
 <code php>
-$OUTPUT->navbar->add($strcategories, $CFG->wwwroot.'/course/index.php');
+if (has_capability('moodle/course:viewparticipants', get_context_instance(CONTEXT_COURSE, $course->id)) || has_capability('moodle/site:viewparticipants', $syscontext)) {
-$OUTPUT->navbar->add(format_string($category->name));
+    $OUTPUT->navbar->add($strparticipants, $CFG->wwwroot.'/user/index.php?id='.$course->id);
+}
+$OUTPUT->navbar->add($strforumposts);
+$OUTPUT->navbar->add($strmode);
+$PAGE->set_heading($course->fullname);
+echo $OUTPUT->header();
 </code>

Documentation