Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.

Differences Between: [Versions 310 and 311] [Versions 311 and 400] [Versions 311 and 401] [Versions 311 and 402] [Versions 311 and 403] [Versions 39 and 311]

This file contains classes used to manage the navigation structures within Moodle.

Copyright: 2009 Sam Hemelryk
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 5913 lines (255 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 12 classes

navigation_node:: (39 methods):
  __construct()
  check_if_active()
  has_siblings()
  get_siblings()
  override_active_url()
  require_admin_tree()
  create()
  add()
  add_node()
  get_children_key_list()
  find()
  build_flat_navigation_list()
  get()
  remove()
  has_children()
  make_active()
  make_inactive()
  force_open()
  add_class()
  remove_class()
  title()
  __wakeup()
  contains_active_node()
  is_short_branch()
  find_active_node()
  search_for_active_node()
  get_content()
  get_title()
  has_action()
  is_hidden()
  get_css_type()
  find_expandable()
  find_all_of_type()
  trim_if_empty()
  get_tabs_array()
  set_parent()
  hide()
  action()
  add_context_locking_node()

navigation_node_collection:: (11 methods):
  add()
  get_key_list()
  set_collectionlabel()
  get_collectionlabel()
  get()
  find()
  last()
  type()
  remove()
  count()
  getIterator()

global_navigation:: (33 methods):
  __construct()
  set_userid_for_parent_checks()
  initialise()
  load_local_plugin_navigation()
  current_user_is_parent_role()
  show_categories()
  show_my_categories()
  load_all_courses()
  can_add_more_courses_to_category()
  load_all_categories()
  add_category()
  load_course()
  load_course_sections()
  generate_sections_and_activities()
  load_generic_course_sections()
  load_section_activities()
  load_stealth_activity()
  load_activity()
  load_for_user()
  module_extends_navigation()
  extend_for_user()
  get_extending_users()
  add_course()
  get_expand_course_cache()
  can_expand_course()
  is_category_fully_loaded()
  add_course_essentials()
  add_front_page_course_essentials()
  clear_cache()
  set_expansion_limit()
  get()
  find()
  load_courses_enrolled()

global_navigation_for_ajax:: (5 methods):
  __construct()
  initialise()
  load_courses_other()
  load_category()
  get_expandable()

navbar:: (8 methods):
  __construct()
  has_items()
  ignore_active()
  get()
  get_items()
  get_course_categories()
  add()
  prepend()

breadcrumb_navigation_node:: (3 methods):
  __construct()
  is_last()
  set_last()

flat_navigation_node:: (9 methods):
  __construct()
  set_collectionlabel()
  get_collectionlabel()
  is_section()
  isactive()
  showdivider()
  set_showdivider()
  get_indent()
  set_indent()

flat_navigation:: (3 methods):
  __construct()
  initialise()
  add()

settings_navigation:: (20 methods):
  __construct()
  initialise()
  add()
  prepend()
  is_admin_tree_needed()
  load_administration_settings()
  scan_for_active_node()
  get_by_path()
  load_course_settings()
  load_module_settings()
  load_user_settings()
  extend_for_user()
  generate_user_settings()
  load_block_settings()
  load_category_settings()
  in_alternative_role()
  load_front_page_settings()
  load_local_plugin_settings()
  clear_cache()
  can_view_user_preferences()

settings_navigation_ajax:: (2 methods):
  __construct()
  initialise()

navigation_json:: (3 methods):
  convert()
  set_expandable()
  convert_child()

navigation_cache:: (11 methods):
  __construct()
  ensure_session_cache_initialised()
  __get()
  __set()
  set()
  cached()
  compare()
  clear()
  garbage_collection()
  volatile()
  destroy_volatile_caches()


Class: navigation_node  - X-Ref

This class is used to represent a node in a navigation tree

This class is used to represent a node in a navigation tree within Moodle,
the tree could be one of global navigation, settings navigation, or the navbar.
Each node can be one of two types either a Leaf (default) or a branch.
When a node is first created it is created as a leaf, when/if children are added
the node then becomes a branch.

__construct($properties)   X-Ref
Constructs a new navigation_node

param: array|string $properties Either an array of properties or a string to use

check_if_active($strength=URL_MATCH_EXACT)   X-Ref
Checks if this node is the active node.

This is determined by comparing the action for the node against the
defined URL for the page. A match will see this node marked as active.

param: int $strength One of URL_MATCH_EXACT, URL_MATCH_PARAMS, or URL_MATCH_BASE
return: bool

has_siblings()   X-Ref
True if this nav node has siblings in the tree.

return: bool

get_siblings()   X-Ref
Get a list of sibling navigation nodes at the same level as this one.

return: bool|array of navigation_node

override_active_url(moodle_url $url, $loadadmintree = false)   X-Ref
This sets the URL that the URL of new nodes get compared to when locating
the active node.

The active node is the node that matches the URL set here. By default this
is either $PAGE->url or if that hasn't been set $FULLME.

param: moodle_url $url The url to use for the fullmeurl.
param: bool $loadadmintree use true if the URL point to administration tree

require_admin_tree()   X-Ref
Use when page is linked from the admin tree,
if not used navigation could not find the page using current URL
because the tree is not fully loaded.


create($text, $action=null, $type=self::TYPE_CUSTOM,$shorttext=null, $key=null, pix_icon $icon=null)   X-Ref
Creates a navigation node, ready to add it as a child using add_node
function. (The created node needs to be added before you can use it.)

param: string $text
param: moodle_url|action_link $action
param: int $type
param: string $shorttext
param: string|int $key
param: pix_icon $icon
return: navigation_node

add($text, $action=null, $type=self::TYPE_CUSTOM, $shorttext=null, $key=null, pix_icon $icon=null)   X-Ref
Adds a navigation node as a child of this node.

param: string $text
param: moodle_url|action_link $action
param: int $type
param: string $shorttext
param: string|int $key
param: pix_icon $icon
return: navigation_node

add_node(navigation_node $childnode, $beforekey=null)   X-Ref
Adds a navigation node as a child of this one, given a $node object
created using the create function.

param: navigation_node $childnode Node to add
param: string $beforekey
return: navigation_node The added node

get_children_key_list()   X-Ref
Return a list of all the keys of all the child nodes.

return: array the keys.

find($key, $type)   X-Ref
Searches for a node of the given type with the given key.

This searches this node plus all of its children, and their children....
If you know the node you are looking for is a child of this node then please
use the get method instead.

param: int|string $key The key of the node we are looking for
param: int $type One of navigation_node::TYPE_*
return: navigation_node|false

build_flat_navigation_list(flat_navigation $nodes, $showdivider = false, $label = '')   X-Ref
Walk the tree building up a list of all the flat navigation nodes.

param: flat_navigation $nodes List of the found flat navigation nodes.
param: boolean $showdivider Show a divider before the first node.
param: string $label A label for the collection of navigation links.

get($key, $type=null)   X-Ref
Get the child of this node that has the given key + (optional) type.

If you are looking for a node and want to search all children + their children
then please use the find method instead.

param: int|string $key The key of the node we are looking for
param: int $type One of navigation_node::TYPE_*
return: navigation_node|false

remove()   X-Ref
Removes this node.

return: bool

has_children()   X-Ref
Checks if this node has or could have any children

return: bool Returns true if it has children or could have (by AJAX expansion)

make_active()   X-Ref
Marks this node as active and forces it open.

Important: If you are here because you need to mark a node active to get
the navigation to do what you want have you looked at {@link navigation_node::override_active_url()}?
You can use it to specify a different URL to match the active navigation node on
rather than having to locate and manually mark a node active.

make_inactive()   X-Ref
Marks a node as inactive and recusised back to the base of the tree
doing the same to all parents.


force_open()   X-Ref
Forces this node to be open and at the same time forces open all
parents until the root node.

Recursive.

add_class($class)   X-Ref
Adds a CSS class to this node.

param: string $class
return: bool

remove_class($class)   X-Ref
Removes a CSS class from this node.

param: string $class
return: bool True if the class was successfully removed.

title($title)   X-Ref
Sets the title for this node and forces Moodle to utilise it.

param: string $title

__wakeup()   X-Ref
Resets the page specific information on this node if it is being unserialised.


contains_active_node()   X-Ref
Checks if this node or any of its children contain the active node.

Recursive.

return: bool

is_short_branch()   X-Ref
To better balance the admin tree, we want to group all the short top branches together.

This means < 8 nodes and no subtrees.

return: bool

find_active_node()   X-Ref
Finds the active node.

Searches this nodes children plus all of the children for the active node
and returns it if found.

Recursive.

return: navigation_node|false

search_for_active_node()   X-Ref
Searches all children for the best matching active node

return: navigation_node|false

get_content($shorttext=false)   X-Ref
Gets the content for this node.

param: bool $shorttext If true shorttext is used rather than the normal text
return: string

get_title()   X-Ref
Gets the title to use for this node.

return: string

has_action()   X-Ref
Used to easily determine if this link in the breadcrumbs has a valid action/url.

return: boolean

is_hidden()   X-Ref
Used to easily determine if this link in the breadcrumbs is hidden.

return: boolean

get_css_type()   X-Ref
Gets the CSS class to add to this node to describe its type

return: string

find_expandable(array &$expandable)   X-Ref
Finds all nodes that are expandable by AJAX

param: array $expandable An array by reference to populate with expandable nodes.

find_all_of_type($type)   X-Ref
Finds all nodes of a given type (recursive)

param: int $type One of navigation_node::TYPE_*
return: array

trim_if_empty()   X-Ref
Removes this node if it is empty


get_tabs_array(array $inactive=array()   X-Ref
Creates a tab representation of this nodes children that can be used
with print_tabs to produce the tabs on a page.

call_user_func_array('print_tabs', $node->get_tabs_array());

param: array $inactive
param: bool $return
return: array Array (tabs, selected, inactive, activated, return)

set_parent(navigation_node $parent)   X-Ref
Sets the parent for this node and if this node is active ensures that the tree is properly
adjusted as well.

param: navigation_node $parent

hide(array $typestohide = null)   X-Ref
Hides the node and any children it has.

param: array $typestohide Optional. An array of node types that should be hidden.

action()   X-Ref
Get the action url for this navigation node.
Called from templates.


add_context_locking_node(\navigation_node $node, \context $context)   X-Ref
Add the menu item to handle locking and unlocking of a conext.

param: \navigation_node $node Node to add
param: \context $context The context to be locked

Class: navigation_node_collection  - X-Ref

Navigation node collection

This class is responsible for managing a collection of navigation nodes.
It is required because a node's unique identifier is a combination of both its
key and its type.

Originally an array was used with a string key that was a combination of the two
however it was decided that a better solution would be to use a class that
implements the standard IteratorAggregate interface.

add(navigation_node $node, $beforekey=null)   X-Ref
Adds a navigation node to the collection

param: navigation_node $node Node to add
param: string $beforekey If specified, adds before a node with this key,
return: navigation_node Added node

get_key_list()   X-Ref
Return a list of all the keys of all the nodes.

return: array the keys.

set_collectionlabel($label)   X-Ref
Set a label for this collection.

param: string $label

get_collectionlabel()   X-Ref
Return a label for this collection.

return: string

get($key, $type=null)   X-Ref
Fetches a node from this collection.

param: string|int $key The key of the node we want to find.
param: int $type One of navigation_node::TYPE_*.
return: navigation_node|null

find($key, $type=null)   X-Ref
Searches for a node with matching key and type.

This function searches both the nodes in this collection and all of
the nodes in each collection belonging to the nodes in this collection.

Recursive.

param: string|int $key  The key of the node we want to find.
param: int $type  One of navigation_node::TYPE_*.
return: navigation_node|null

last()   X-Ref
Fetches the last node that was added to this collection

return: navigation_node

type($type)   X-Ref
Fetches all nodes of a given type from this collection

param: string|int $type  node type being searched for.
return: array ordered collection

remove($key, $type=null)   X-Ref
Removes the node with the given key and type from the collection

param: string|int $key The key of the node we want to find.
param: int $type
return: bool

count()   X-Ref
Gets the number of nodes in this collection

This option uses an internal count rather than counting the actual options to avoid
a performance hit through the count function.

return: int

getIterator()   X-Ref
Gets an array iterator for the collection.

This is required by the IteratorAggregator interface and is used by routines
such as the foreach loop.

return: ArrayIterator

Class: global_navigation  - X-Ref

The global navigation class used for... the global navigation

This class is used by PAGE to store the global navigation for the site
and is then used by the settings nav and navbar to save on processing and DB calls

See
{@link lib/pagelib.php} {@link moodle_page::initialise_theme_and_output()}
{@link lib/ajax/getnavbranch.php} Called by ajax

__construct(moodle_page $page)   X-Ref
Constructs a new global navigation

param: moodle_page $page The page this navigation object belongs to

set_userid_for_parent_checks($userid)   X-Ref
Mutator to set userid to allow parent to see child's profile
page navigation. See MDL-25805 for initial issue. Linked to it
is an issue explaining why this is a REALLY UGLY HACK thats not
for you to use!

param: int $userid userid of profile page that parent wants to navigate around.

initialise()   X-Ref
Initialises the navigation object.

This causes the navigation object to look at the current state of the page
that it is associated with and then load the appropriate content.

This should only occur the first time that the navigation structure is utilised
which will normally be either when the navbar is called to be displayed or
when a block makes use of it.

return: bool

load_local_plugin_navigation()   X-Ref
This function gives local plugins an opportunity to modify navigation.


current_user_is_parent_role()   X-Ref
Returns true if the current user is a parent of the user being currently viewed.

If the current user is not viewing another user, or if the current user does not hold any parent roles over the
other user being viewed this function returns false.
In order to set the user for whom we are checking against you must call {@link set_userid_for_parent_checks()}

return: bool

show_categories($ismycourse = false)   X-Ref
Returns true if courses should be shown within categories on the navigation.

param: bool $ismycourse Set to true if you are calculating this for a course.
return: bool

show_my_categories()   X-Ref
Returns true if we should show categories in the My Courses branch.

return: bool

load_all_courses($categoryids = null)   X-Ref
Loads the courses in Moodle into the navigation.

param: string|array $categoryids An array containing categories to load courses
return: array An array of navigation_nodes one for each course

can_add_more_courses_to_category($category)   X-Ref
Returns true if more courses can be added to the provided category.

param: int|navigation_node|stdClass $category
return: bool

load_all_categories($categoryid = self::LOAD_ROOT_CATEGORIES, $showbasecategories = false)   X-Ref
Loads all categories (top level or if an id is specified for that category)

param: int $categoryid The category id to load or null/0 to load all base level categories
param: bool $showbasecategories If set to true all base level categories will be loaded as well
return: navigation_node|void returns a navigation node if a category has been loaded.

add_category(stdClass $category, navigation_node $parent, $nodetype = self::TYPE_CATEGORY)   X-Ref
Adds a structured category to the navigation in the correct order/place

param: stdClass $category category to be added in navigation.
param: navigation_node $parent parent navigation node
param: int $nodetype type of node, if category is under MyHome then it's TYPE_MY_CATEGORY
return: void.

load_course(stdClass $course)   X-Ref
Loads the given course into the navigation

param: stdClass $course
return: navigation_node

load_course_sections(stdClass $course, navigation_node $coursenode, $sectionnum = null, $cm = null)   X-Ref
Loads all of the courses section into the navigation.

This function calls method from current course format, see
{@link format_base::extend_course_navigation()}
If course module ($cm) is specified but course format failed to create the node,
the activity node is created anyway.

By default course formats call the method {@link global_navigation::load_generic_course_sections()}

param: stdClass $course Database record for the course
param: navigation_node $coursenode The course node within the navigation
param: null|int $sectionnum If specified load the contents of section with this relative number
param: null|cm_info $cm If specified make sure that activity node is created (either

generate_sections_and_activities(stdClass $course)   X-Ref
Generates an array of sections and an array of activities for the given course.

This method uses the cache to improve performance and avoid the get_fast_modinfo call

param: stdClass $course
return: array Array($sections, $activities)

load_generic_course_sections(stdClass $course, navigation_node $coursenode)   X-Ref
Generically loads the course sections into the course's navigation.

param: stdClass $course
param: navigation_node $coursenode
return: array An array of course section nodes

load_section_activities(navigation_node $sectionnode, $sectionnumber, array $activities, $course = null)   X-Ref
Loads all of the activities for a section into the navigation structure.

param: navigation_node $sectionnode
param: int $sectionnumber
param: array $activities An array of activites as returned by {@link global_navigation::generate_sections_and_activities()}
param: stdClass $course The course object the section and activities relate to.
return: array Array of activity nodes

load_stealth_activity(navigation_node $coursenode, $modinfo)   X-Ref
Loads a stealth module from unavailable section

param: navigation_node $coursenode
param: stdClass $modinfo
return: navigation_node or null if not accessible

load_activity($cm, stdClass $course, navigation_node $activity)   X-Ref
Loads the navigation structure for the given activity into the activities node.

This method utilises a callback within the modules lib.php file to load the
content specific to activity given.

The callback is a method: {modulename}_extend_navigation()
Examples:
* {@link forum_extend_navigation()}
* {@link workshop_extend_navigation()}

param: cm_info|stdClass $cm
param: stdClass $course
param: navigation_node $activity
return: bool

load_for_user($user=null, $forceforcontext=false)   X-Ref
Loads user specific information into the navigation in the appropriate place.

If no user is provided the current user is assumed.

param: stdClass $user
param: bool $forceforcontext probably force something to be loaded somewhere (ask SamH if not sure what this means)
return: bool

module_extends_navigation($modname)   X-Ref
This method simply checks to see if a given module can extend the navigation.

param: string $modname
return: bool

extend_for_user($user)   X-Ref
Extends the navigation for the given user.

param: stdClass $user A user from the database

get_extending_users()   X-Ref
Returns all of the users the navigation is being extended for

return: array An array of extending users.

add_course(stdClass $course, $forcegeneric = false, $coursetype = self::COURSE_OTHER)   X-Ref
Adds the given course to the navigation structure.

param: stdClass $course
param: bool $forcegeneric
param: bool $ismycourse
return: navigation_node

get_expand_course_cache()   X-Ref
Returns a cache instance to use for the expand course cache.

return: cache_session

can_expand_course($course)   X-Ref
Checks if a user can expand a course in the navigation.

We use a cache here because in order to be accurate we need to call can_access_course which is a costly function.
Because this functionality is basic + non-essential and because we lack good event triggering this cache
permits stale data.
In the situation the user is granted access to a course after we've initialised this session cache the cache
will be stale.
It is brought up to date in only one of two ways.
1. The user logs out and in again.
2. The user browses to the course they've just being given access to.

Really all this controls is whether the node is shown as expandable or not. It is uber un-important.

param: stdClass $course
return: bool

is_category_fully_loaded($categoryid)   X-Ref
Returns true if the category has already been loaded as have any child categories

param: int $categoryid
return: bool

add_course_essentials($coursenode, stdClass $course)   X-Ref
Adds essential course nodes to the navigation for the given course.

This method adds nodes such as reports, blogs and participants

param: navigation_node $coursenode
param: stdClass $course
return: bool returns true on successful addition of a node.

add_front_page_course_essentials(navigation_node $coursenode, stdClass $course)   X-Ref
This generates the structure of the course that won't be generated when
the modules and sections are added.

Things such as the reports branch, the participants branch, blogs... get
added to the course node by this method.

param: navigation_node $coursenode
param: stdClass $course
return: bool True for successfull generation

clear_cache()   X-Ref
Clears the navigation cache


set_expansion_limit($type)   X-Ref
Sets an expansion limit for the navigation

The expansion limit is used to prevent the display of content that has a type
greater than the provided $type.

Can be used to ensure things such as activities or activity content don't get
shown on the navigation.
They are still generated in order to ensure the navbar still makes sense.

param: int $type One of navigation_node::TYPE_*
return: bool true when complete.

get($key, $type = null)   X-Ref
Attempts to get the navigation with the given key from this nodes children.

This function only looks at this nodes children, it does NOT look recursivily.
If the node can't be found then false is returned.

If you need to search recursivily then use the {@link global_navigation::find()} method.

Note: If you are trying to set the active node {@link navigation_node::override_active_url()}
may be of more use to you.

param: string|int $key The key of the node you wish to receive.
param: int $type One of navigation_node::TYPE_*
return: navigation_node|false

find($key, $type)   X-Ref
Searches this nodes children and their children to find a navigation node
with the matching key and type.

This method is recursive and searches children so until either a node is
found or there are no more nodes to search.

If you know that the node being searched for is a child of this node
then use the {@link global_navigation::get()} method instead.

Note: If you are trying to set the active node {@link navigation_node::override_active_url()}
may be of more use to you.

param: string|int $key The key of the node you wish to receive.
param: int $type One of navigation_node::TYPE_*
return: navigation_node|false

load_courses_enrolled()   X-Ref
They've expanded the 'my courses' branch.


Class: global_navigation_for_ajax  - X-Ref

The global navigation class used especially for AJAX requests.

The primary methods that are used in the global navigation class have been overriden
to ensure that only the relevant branch is generated at the root of the tree.
This can be done because AJAX is only used when the backwards structure for the
requested branch exists.
This has been done only because it shortens the amounts of information that is generated
which of course will speed up the response time.. because no one likes laggy AJAX.

__construct($page, $branchtype, $id)   X-Ref
Constructs the navigation for use in an AJAX request

param: moodle_page $page moodle_page object
param: int $branchtype
param: int $id

initialise()   X-Ref
Initialise the navigation given the type and id for the branch to expand.

return: array An array of the expandable nodes

load_courses_other()   X-Ref
They've expanded the general 'courses' branch.


load_category($categoryid, $nodetype = self::TYPE_CATEGORY)   X-Ref
Loads a single category into the AJAX navigation.

This function is special in that it doesn't concern itself with the parent of
the requested category or its siblings.
This is because with the AJAX navigation we know exactly what is wanted and only need to
request that.

param: int $categoryid id of category to load in navigation.
param: int $nodetype type of node, if category is under MyHome then it's TYPE_MY_CATEGORY
return: void.

get_expandable()   X-Ref
Returns an array of expandable nodes

return: array

Class: navbar  - X-Ref

Navbar class

This class is used to manage the navbar, which is initialised from the navigation
object held by PAGE

__construct(moodle_page $page)   X-Ref
The almighty constructor

param: moodle_page $page

has_items()   X-Ref
Quick check to see if the navbar will have items in.

return: bool Returns true if the navbar will have items, false otherwise

ignore_active($setting=true)   X-Ref
Turn on/off ignore active

param: bool $setting

get($key, $type = null)   X-Ref
Gets a navigation node

param: string|int $key for referencing the navbar nodes
param: int $type breadcrumb_navigation_node::TYPE_*
return: breadcrumb_navigation_node|bool

get_items()   X-Ref
Returns an array of breadcrumb_navigation_nodes that make up the navbar.

return: array

get_course_categories()   X-Ref
Get the list of categories leading to this course.

This function is used by {@link navbar::get_items()} to add back the "courses"
node and category chain leading to the current course.  Note that this is only ever
called for the current course, so we don't need to bother taking in any parameters.

return: array

add($text, $action=null, $type=self::TYPE_CUSTOM, $shorttext=null, $key=null, pix_icon $icon=null)   X-Ref
Add a new breadcrumb_navigation_node to the navbar, overrides parent::add

This function overrides {@link breadcrumb_navigation_node::add()} so that we can change
the way nodes get added to allow us to simply call add and have the node added to the
end of the navbar

param: string $text
param: string|moodle_url|action_link $action An action to associate with this node.
param: int $type One of navigation_node::TYPE_*
param: string $shorttext
param: string|int $key A key to identify this node with. Key + type is unique to a parent.
param: pix_icon $icon An optional icon to use for this node.
return: navigation_node

prepend($text, $action=null, $type=self::TYPE_CUSTOM, $shorttext=null, $key=null, pix_icon $icon=null)   X-Ref
Prepends a new navigation_node to the start of the navbar

param: string $text
param: string|moodle_url|action_link $action An action to associate with this node.
param: int $type One of navigation_node::TYPE_*
param: string $shorttext
param: string|int $key A key to identify this node with. Key + type is unique to a parent.
param: pix_icon $icon An optional icon to use for this node.
return: navigation_node

Class: breadcrumb_navigation_node  - X-Ref

Subclass of navigation_node allowing different rendering for the breadcrumbs
in particular adding extra metadata for search engine robots to leverage.

__construct($navnode)   X-Ref
A proxy constructor

param: mixed $navnode A navigation_node or an array

is_last()   X-Ref
Getter for "last"

return: boolean

set_last($val)   X-Ref
Setter for "last"

param: $val boolean

Class: flat_navigation_node  - X-Ref

Subclass of navigation_node allowing different rendering for the flat navigation
in particular allowing dividers and indents.

__construct($navnode, $indent)   X-Ref
A proxy constructor

param: mixed $navnode A navigation_node or an array

set_collectionlabel($label)   X-Ref
Setter, a label is required for a flat navigation node that shows a divider.

param: string $label

get_collectionlabel()   X-Ref
Getter, get the label for this flat_navigation node, or it's parent if it doesn't have one.

return: string

is_section()   X-Ref
Does this node represent a course section link.

return: boolean

isactive()   X-Ref
In flat navigation - sections are active if we are looking at activities in the section.

return: boolean

showdivider()   X-Ref
Getter for "showdivider"

return: boolean

set_showdivider($val, $label = '')   X-Ref
Setter for "showdivider"

param: $val boolean
param: $label string Label for the group of nodes

get_indent()   X-Ref
Getter for "indent"

return: boolean

set_indent($val)   X-Ref
Setter for "indent"

param: $val boolean

Class: flat_navigation  - X-Ref

Class used to generate a collection of navigation nodes most closely related
to the current page.

__construct(moodle_page &$page)   X-Ref
Constructor.

param: moodle_page $page

initialise()   X-Ref
Build the list of navigation nodes based on the current navigation and settings trees.


add(navigation_node $node, $beforekey=null)   X-Ref
Override the parent so we can set a label for this collection if it has not been set yet.

param: navigation_node $node Node to add
param: string $beforekey If specified, adds before a node with this key,
return: navigation_node Added node

Class: settings_navigation  - X-Ref

Class used to manage the settings option for the current page

This class is used to manage the settings options in a tree format (recursively)
and was created initially for use with the settings blocks.

__construct(moodle_page &$page)   X-Ref
Sets up the object with basic settings and preparse it for use

param: moodle_page $page

initialise()   X-Ref
Initialise the settings navigation based on the current context

This function initialises the settings navigation tree for a given context
by calling supporting functions to generate major parts of the tree.


add($text, $url=null, $type=null, $shorttext=null, $key=null, pix_icon $icon=null)   X-Ref
Override the parent function so that we can add preceeding hr's and set a
root node class against all first level element

It does this by first calling the parent's add method {@link navigation_node::add()}
and then proceeds to use the key to set class and hr

param: string $text text to be used for the link.
param: string|moodle_url $url url for the new node
param: int $type the type of node navigation_node::TYPE_*
param: string $shorttext
param: string|int $key a key to access the node by.
param: pix_icon $icon An icon that appears next to the node.
return: navigation_node with the new node added to it.

prepend($text, $url=null, $type=null, $shorttext=null, $key=null, pix_icon $icon=null)   X-Ref
This function allows the user to add something to the start of the settings
navigation, which means it will be at the top of the settings navigation block

param: string $text text to be used for the link.
param: string|moodle_url $url url for the new node
param: int $type the type of node navigation_node::TYPE_*
param: string $shorttext
param: string|int $key a key to access the node by.
param: pix_icon $icon An icon that appears next to the node.
return: navigation_node $node with the new node added to it.

is_admin_tree_needed()   X-Ref
Does this page require loading of full admin tree or is
it enough rely on AJAX?

return: bool

load_administration_settings(navigation_node $referencebranch=null, part_of_admin_tree $adminbranch=null)   X-Ref
Load the site administration tree

This function loads the site administration tree by using the lib/adminlib library functions

param: navigation_node $referencebranch A reference to a branch in the settings
param: part_of_admin_tree $adminbranch The branch to add, if null generate the admin
return: mixed A key to access the admin tree by

scan_for_active_node(navigation_node $node)   X-Ref
This function recursivily scans nodes until it finds the active node or there
are no more nodes.

param: navigation_node $node

get_by_path(array $path)   X-Ref
Gets a navigation node given an array of keys that represent the path to
the desired node.

param: array $path
return: navigation_node|false

load_course_settings($forceopen = false)   X-Ref
This function loads the course settings that are available for the user

param: bool $forceopen If set to true the course node will be forced open
return: navigation_node|false

load_module_settings()   X-Ref
This function calls the module function to inject module settings into the
settings navigation tree.

This only gets called if there is a corrosponding function in the modules
lib file.

For examples mod/forum/lib.php {@link forum_extend_settings_navigation()}

return: navigation_node|false

load_user_settings($courseid = SITEID)   X-Ref
Loads the user settings block of the settings nav

This function is simply works out the userid and whether we need to load
just the current users profile settings, or the current user and the user the
current user is viewing.

This function has some very ugly code to work out the user, if anyone has
any bright ideas please feel free to intervene.

param: int $courseid The course id of the current course
return: navigation_node|false

extend_for_user($userid)   X-Ref
Extends the settings navigation for the given user.

Note: This method gets called automatically if you call
$PAGE->navigation->extend_for_user($userid)

param: int $userid

generate_user_settings($courseid, $userid, $gstitle='usercurrentsettings')   X-Ref
This function gets called by {@link settings_navigation::load_user_settings()} and actually works out
what can be shown/done

param: int $courseid The current course' id
param: int $userid The user id to load for
param: string $gstitle The string to pass to get_string for the branch title
return: navigation_node|false

load_block_settings()   X-Ref
Loads block specific settings in the navigation

return: navigation_node

load_category_settings()   X-Ref
Loads category specific settings in the navigation

return: navigation_node

in_alternative_role()   X-Ref
Determine whether the user is assuming another role

This function checks to see if the user is assuming another role by means of
role switching. In doing this we compare each RSW key (context path) against
the current context path. This ensures that we can provide the switching
options against both the course and any page shown under the course.

return: bool|int The role(int) if the user is in another role, false otherwise

load_front_page_settings($forceopen = false)   X-Ref
This function loads all of the front page settings into the settings navigation.
This function is called when the user is on the front page, or $COURSE==$SITE

param: bool $forceopen (optional)
return: navigation_node

load_local_plugin_settings()   X-Ref
This function gives local plugins an opportunity to modify the settings navigation.


clear_cache()   X-Ref
This function marks the cache as volatile so it is cleared during shutdown


can_view_user_preferences($userid)   X-Ref
Checks to see if there are child nodes available in the specific user's preference node.
If so, then they have the appropriate permissions view this user's preferences.

param: int $userid The user's ID.
return: bool True if child nodes exist to view, otherwise false.

Class: settings_navigation_ajax  - X-Ref

Class used to populate site admin navigation for ajax.

__construct(moodle_page &$page)   X-Ref
Constructs the navigation for use in an AJAX request

param: moodle_page $page

initialise()   X-Ref
Initialise the site admin navigation.

return: array An array of the expandable nodes

Class: navigation_json  - X-Ref

Simple class used to output a navigation branch in XML

convert($branch)   X-Ref
Turns a branch and all of its children into XML

param: navigation_node $branch
return: string XML string

set_expandable($expandable)   X-Ref
Set the expandable items in the array so that we have enough information
to attach AJAX events

param: array $expandable

convert_child($child, $depth=1)   X-Ref
Recusively converts a child node and its children to XML for output

param: navigation_node $child The child to convert
param: int $depth Pointlessly used to track the depth of the XML structure
return: string JSON

Class: navigation_cache  - X-Ref

The cache class used by global navigation and settings navigation.

It is basically an easy access point to session with a bit of smarts to make
sure that the information that is cached is valid still.

Example use:
<code php>
if (!$cache->viewdiscussion()) {
// Code to do stuff and produce cachable content
$cache->viewdiscussion = has_capability('mod/forum:viewdiscussion', $coursecontext);
}
$content = $cache->viewdiscussion;
</code>

__construct($area, $timeout=1800)   X-Ref
Contructor for the cache. Requires two arguments

param: string $area The string to use to segregate this particular cache
param: int $timeout The number of seconds to time the information out after

ensure_session_cache_initialised()   X-Ref
Used to set up the cache within the SESSION.

This is called for each access and ensure that we don't put anything into the session before
it is required.

__get($key)   X-Ref
Magic Method to retrieve something by simply calling using = cache->key

param: mixed $key The identifier for the information you want out again
return: void|mixed Either void or what ever was put in

__set($key, $information)   X-Ref
Magic method that simply uses {@link set();} to store something in the cache

param: string|int $key
param: mixed $information

set($key, $information)   X-Ref
Sets some information against the cache (session) for later retrieval

param: string|int $key
param: mixed $information

cached($key)   X-Ref
Check the existence of the identifier in the cache

param: string|int $key
return: bool

compare($key, $value, $serialise = true)   X-Ref
Compare something to it's equivilant in the cache

param: string $key
param: mixed $value
param: bool $serialise Whether to serialise the value before comparison
return: bool If the value is the same false if it is not set or doesn't match

clear()   X-Ref
Wipes the entire cache, good to force regeneration


garbage_collection()   X-Ref
Checks all cache entries and removes any that have expired, good ole cleanup


volatile($setting = true)   X-Ref
Marks the cache as being volatile (likely to change)

Any caches marked as volatile will be destroyed at the on shutdown by
{@link navigation_node::destroy_volatile_caches()} which is registered
as a shutdown function if any caches are marked as volatile.

param: bool $setting True to destroy the cache false not too

destroy_volatile_caches()   X-Ref
Destroys all caches marked as volatile

This function is static and works in conjunction with the static volatilecaches
property of navigation cache.
Because this function is static it manually resets the cached areas back to an
empty array.