MoodleDocs - User contributions [en]

Using the Moodle App in a browser

2019-11-27T11:46:29Z

Brianlmerritt: Update re issues when running the browser and it ignores the flags when the same browser is already running.

Chromium or Google Chrome browser are the recommended tools for Moodle Mobile development. But remember that if you are going to use functions provided by Phonegap you should use the Android SDK or iOs developer tools.
{{Moodle Mobile}}
{{Work in progress}}

== Differences between Chromium and Google Chrome ==

Google Chrome is the Chromium open source project built, packaged, and distributed by Google. We can say that Chromium is Google Chrome without the "Google" add-ons

See https://code.google.com/p/chromium/wiki/ChromiumBrowserVsGoogleChrome for more information

We recommend using Chromium instead Google Chrome

== Advantages and disadvantages of using Chromium/Google Chrome ==

Main advantages
* Quick development
* DOM inspector
* Network monitor
* Database (local storage) inspector
* Emulation options

Disadvantages
* You can't test/develop using Phonegap APIs and Plugins
* If you use custom Phonegap code (including plugins) you will need to edit the mm.cordova.js for "emulate" those APIs in a browser
* You will always need to test in a real device and emulator prior to a production release
* You will need to verify that your CSS/layout works the same in an Android/iOs device

== Installation ==

Install the “Chromium” browser just downloading it from https://download-chromium.appspot.com/

In order to be able to access any domain via AJAX from the local file:/// protocol, you must run Chromium or Google Chrome in Unsafe mode adding this param:

--allow-file-access-from-files --disable-web-security --user-data-dir --allow-running-insecure-content

NOTE: Since Moodle 3.0 an onwards this shouldn't be necessary since the Web Service layer supports CORS requests apart from download assets such as your branded css.

IMPORTANT: I strongly recommend you create a new link or application launch called "Chrome Unsafe" and use it only for testing the app. Better if you only use this browser for development. In Linux and possibly other operating systems the below arguments only work if you don't already have the same browser running without the args. Hence if you use "google-chrome" as your normal browser then use "chromium-browser" for your cors free debugging and vice versa.

How to open the browser:

"Path to chrome\chrome.exe" --allow-file-access-from-files --disable-web-security --user-data-dir --allow-running-insecure-content

or in Mac (you can use Automator for creating an app bundle)

open -a "Google Chrome" --args --allow-file-access-from-files --disable-web-security --user-data-dir --allow-running-insecure-content

or for Chromium

open -a /Applications/Chromium.app --args --allow-file-access-from-files --disable-web-security --user-data-dir --allow-running-insecure-content

In Mac you can use Automator for creating a launching app

Now, you can open the application running:
ionic serve --browser chromium
it should open a new tab in the current Chromium instance with the app, (remember that you have to open first the Chromium so it's started with all the additional arguments).

If the ionic serve command open a new browser window, you should copy the URL and then paste it in the Chromium instance you opened using the command shell.

== Sites for testing ==

You can test the application using existing sites configured to have the Mobile services enabled.

Real test site: If you type "student" or "teacher" in the "Site URL" field and then tap on "Add site" the app will connect to http://school.demo.moodle.net. This site is reset every hour so you may find unexpected behaviors

== Browser Settings ==
[[{{ns:file}}:moodlemobile_developer.png|thumb|300px]]
You should develop always with the "Developer tools" panel open, you can open that panel with F12 (cmd + alt + i in Mac) or "Developer tools" in the Tools menu.

[[{{ns:file}}:moodlemobile_options.png|left]] Once opened, click on the wheel top-right corner to see the General options, you must Disable the cache there (this setting will work only if you have the Developer tools panel open)

You can dock or undock into a separate window the developer panel using the "Dock" option just at the right of the settings wheel, you can move the developer panel to your right and resize the main browser window to emulate a Mobile device

== Inspecting and changing the DOM ==

Using the "Elements" option you can manipulate the DOM:

* Add/modify style to elements
* Delete elements
* Move elements
* Inject HTML code

You have complete information here: https://developer.chrome.com/devtools/index

And also a free interactive course here: https://www.codeschool.com/courses/discover-devtools

== Monitor XHR (ajax) requests ==
[[{{ns:file}}:moodlemobile_network.png|thumb|300px]]

With the network panel you can check and filter all the HTTP request send from the app to your Moodle server.

You can preserve the log in the navigation, filter by type of requests and also see complete information of all the requests made to the server where is hosted your Moodle installation.

You can also identify with resources takes long to load

== Console, log and errors ==
[[{{ns:file}}:moodlemobile_log.png|thumb|300px]]

The console panel is used for displaying the app log and errors, you can also configure Chrome for displaying there XHR requests

In order to view the app log, you need first to enable Logging in the app (Options / Developers / Enable logging)

You can use the console also for executing javascript commands, the console has access to the complete MM global object so you can call from there to core APIs functions of the app

== Browsing the data base ==
[[{{ns:file}}:moodlemobile_localstorage.png|thumb|300px]]

The Mobile app stores information in the local HTML5 IndexedDB

You can inspect the local database in the Resources tab.

== File system ==
[[{{ns:file}}:moodlemobile_filesystem.png|thumb|300px]]

The first time you open the browser with the special flags you will see a couple of warnings, one asking you to accept to store information.

You have to "Accept" that warning because it means that you will be able to emulate the device file system using the browser.

For example, you will be able to download files to the browser storage (like the user profiles images, any resource in the course, etc..)

You can browse the files stored in the application going to Settings > About and clicking the Filesystem root link.

== Emulating devices ==
[[{{ns:file}}:moodlemobile_emulation.png|thumb|300px]]

You can emulate mobile devices changing orientation, resolution, geo-location, touch events... It's not recommended to use de "Emulation Device" option because it just changes the user-agent and you could get some fails because of the jQuery Swipe library.

The best option to test with the browser is just rescaling the window to get a new viewport size or use the screen settings in the "Emulation" screen.

== See also ==

[https://developer.chrome.com/devtools/index Chrome Developer Tools help]

[[Category: Mobile]]

Setting up your development environment for Moodle Mobile 2 (Ionic 1)

2016-09-13T08:44:58Z

Brianlmerritt: /* Requirements */

{{Moodle Mobile}}
{{Work in progress}}

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

== Requirements ==

'''Install a browser for development'''

I recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read Moodle_Mobile_development_using_Chrome_or_Chromium for more information

'''Install Node.js'''

http://nodejs.org for Mac users I recommend to install nodejs via macports.

'''IMPORTANT''': Don't use node 4.0 or higher, there are incompatibilities with some of the packages we use. Please use v0.12.7 instead. The download directory for v0.12.7 is [https://nodejs.org/dist/v0.12.7/ here]

"note": if you also need later versions of node for other projects, use Node Version Manager aka "nvm" [https://github.com/creationix/nvm here]. Linux and OSX is supported, and the site has pointers to windows alternatives. Simply type:
nvm install 0.12.15
nvm use 0.12.15

'''Install ionic:'''
npm cache clean
npm install -g cordova ionic

'''Clone the code base into a local directory in your computer.'''
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory

'''Install the npm plugins dependencies'''
npm install (This will install all the dependencies listed in package.json)
sudo npm install -g bower (This will install bower in a folder that should be in the PATH)
sudo npm install -g gulp (This will install gulp in a folder that should be in the PATH)

'''Add the iOS and Android platforms and install the required Cordova plugins'''

Install the platforms. It's important to use these versions because newer versions are going to cause some problems with the plugins installed.
ionic platform add android@4.1.1
ionic platform add ios@3.9.1

Run the following command to install the platforms and all the required Cordova plugins
ionic state restore

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json file and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

'''Install bower globally and the required javascript files'''
bower install (this will install all the libraries listed in bower.json)

'''Run gulp’s default tasks (in order to create the build files)'''
gulp

'''Open the app in the browser'''

First start chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium

== Editor ==

There are several plugins for AngularJS and Ionic development available for common editors.

Sublime 3 has plugins for [https://github.com/SublimeLinter/SublimeLinter-jscs jscs] (coding style) and [https://github.com/SublimeLinter/SublimeLinter-jshint jshint] (linter)

Configuration files for jscs and jshint can be downloaded from https://github.com/angular/angular.js (.jscs.json and .jshint*)

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

ionic platform update android
ionic platform update ios

== Updating plugins ==

cordova plugin rm your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see this guide to be able to build for Android and iOS using the command line:

http://cordova.apache.org/docs/en/5.0.0/guide_platforms_index.md.html#Platform%20Guides

'''Common errors when building'''

* com.android.dex.DexException: Multiple dex files define XXX
Open the file ''platforms/android/build.gradle'' and add these code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

* Could not resolve all dependencies for configuration ':_debugCompile'.
Open the Android SDK Manager and make sure you have installed: Android Support Repository, Android Support Library, Google Play Services and Google Repository.

== Troubleshooting ==

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

== See also ==

http://ionicframework.com/docs/cli/

Setting up your development environment for Moodle Mobile 2 (Ionic 1)

2016-09-13T08:32:50Z

Brianlmerritt: /* Requirements */

{{Moodle Mobile}}
{{Work in progress}}

== Overview ==
The majority of your development work will be done using the browser. You will likely begin to use an emulator once you need to simulate a real mobile device.

== Requirements ==

'''Install a browser for development'''

I recommend Chromium browser (Google Chrome open source version) https://download-chromium.appspot.com/
Please, read Moodle_Mobile_development_using_Chrome_or_Chromium for more information

'''Install Node.js'''

http://nodejs.org for Mac users I recommend to install nodejs via macports.

'''IMPORTANT''': Don't use node 4.0 or higher, there are incompatibilities with some of the packages we use. Please use v0.12.7 instead. The download directory for v0.12.7 is [https://nodejs.org/dist/v0.12.7/ here]

"note": if you also need later versions of node for other projects, use Node Version Manager aka "nvm" [https://github.com/creationix/nvm here]. Linux and OSX is supported, and the site has pointers to windows alternatives. Simply type:
nvm install 0.12.25
nvm use 0.12.25

'''Install ionic:'''
npm cache clean
npm install -g cordova ionic

'''Clone the code base into a local directory in your computer.'''
git clone https://github.com/moodlehq/moodlemobile2.git moodlemobiledirectory
cd moodlemobiledirectory

'''Install the npm plugins dependencies'''
npm install (This will install all the dependencies listed in package.json)
sudo npm install -g bower (This will install bower in a folder that should be in the PATH)
sudo npm install -g gulp (This will install gulp in a folder that should be in the PATH)

'''Add the iOS and Android platforms and install the required Cordova plugins'''

Install the platforms. It's important to use these versions because newer versions are going to cause some problems with the plugins installed.
ionic platform add android@4.1.1
ionic platform add ios@3.9.1

Run the following command to install the platforms and all the required Cordova plugins
ionic state restore

Please, note that if you are creating a custom app with a custom URL scheme, you should edit the /package.json file and specify there your custom URL_SCHEME (replacing the existing value) and your [https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/INSTALLATION.md GCMPN SENDER_ID].

'''Install bower globally and the required javascript files'''
bower install (this will install all the libraries listed in bower.json)

'''Run gulp’s default tasks (in order to create the build files)'''
gulp

'''Open the app in the browser'''

First start chromium via the command line using the custom parameters as is mentioned here: [[Moodle Mobile development using Chrome or Chromium]]

and then, start the Ionic server:

ionic serve --browser chromium

== Editor ==

There are several plugins for AngularJS and Ionic development available for common editors.

Sublime 3 has plugins for [https://github.com/SublimeLinter/SublimeLinter-jscs jscs] (coding style) and [https://github.com/SublimeLinter/SublimeLinter-jshint jshint] (linter)

Configuration files for jscs and jshint can be downloaded from https://github.com/angular/angular.js (.jscs.json and .jshint*)

== Updating ionic and cordova ==

sudo npm update -g cordova
sudo npm update -g ionic

ionic platform update android
ionic platform update ios

== Updating plugins ==

cordova plugin rm your_plugin_id
cordova plugin add your_plugin_id

== Building for Android and iOS ==

Please see this guide to be able to build for Android and iOS using the command line:

http://cordova.apache.org/docs/en/5.0.0/guide_platforms_index.md.html#Platform%20Guides

'''Common errors when building'''

* com.android.dex.DexException: Multiple dex files define XXX
Open the file ''platforms/android/build.gradle'' and add these code at the end:

configurations {
all*.exclude group: 'com.android.support', module: 'support-v4'
}

* Could not resolve all dependencies for configuration ':_debugCompile'.
Open the Android SDK Manager and make sure you have installed: Android Support Repository, Android Support Library, Google Play Services and Google Repository.

== Troubleshooting ==

=== Error: libsass bindings not found. Try reinstalling node-sass? ===

Please read: http://fettblog.eu/gulp-and-node4-first-aid/, alternatively you must be sure that you installed Node v0.12

== See also ==

http://ionicframework.com/docs/cli/

Using images in a theme

2013-04-11T10:10:33Z

Brianlmerritt: /* Using your images within your layout files */

{{Template:Themes}}{{Moodle 2.0}}
==A little background==
Moodle 2.0 has introduced a new improved method of making use of images within its pages enabling theme designers to take full control over what images are being used and when possible ensures images are passed through Moodle's new performance caching system to obtain the best possible performance.

$CFG->themewww and custom pix in Moodle 1.9 and lower are gone from Moodle 2.0 and have been replaced by this new system.

==Before we start==

# Make sure you have a theme and images to work with, one that you have a backup of just in case.
# Take note of your theme's main layout file e.g. ''standard.php''.
# Take note of your theme's main CSS file e.g. ''core.css''.
# Turn on '''Theme designer mode'''.

==Image locations within Moodle==

There are three main areas in which images are located - core, plugin and theme.

Core images are used throughout Moodle and are stored in ''moodle/pix''.

The pix directory contains the following subdirectories:

:''a'' - Icons that are not widely used
:''c'' - Calendar-related icons
:''f'' - File icons for different file types
:''g'' - Default user icons and thumbnails
:''i'' - General icons
:''m'' - Currency symbols
:''s'' - Smileys
:''t'' - General icons
:''u'' - User icons and thumbnails
:''y'' - YUI icons

Plugin images are used by plugins and are stored within the plugin's directory e.g. ''mod/forum/*'' or ''blocks/navigation/*''

Theme images are used in themes and are stored in the ''pix'' subdirectory of a theme.

==Adding new images to your theme==

To add new images to your theme, such as a background image or a logo, you should start by creating a pix directory within your themes directory.

Lets assume you have two images, gradient.png and logo.jpg. Copy both files to your themes pix directory.

The plan is to use gradient.png as the background image for your theme (in CSS) and use logo.jpg in the header (in your theme's layout file).

===Using images within CSS===

Moodle parses all CSS files. When theme designer mode is off, Moodle combines them into a handful of large CSS files that get cached and served. At the same time Moodle also looks at the CSS and replaces special syntax rules.

<div style='padding:10px;background-color:#f7f7f7;border:1px dashed #123456'><nowiki>[[pix:theme|</nowiki><span style='color:#336699;font-weight:bold;'><nowiki>path/to/image/</nowiki></span><span style='color:#33993A;font-weight:bold;'>imagename</span><nowiki>]]</nowiki></div>

The above pattern is looked for by Moodle and gets replaced with the correct image URL when found.
You should note the following things about this pattern when using your own images within CSS:

# The bits in black don't change
# The bit in blue is the path to your image within the pix directory. It shouldn't start with a / but should end with one.
# The bit in green is the filename ('''no need to include the file extension''')

To use background.png as the background for our pages, add the following line of CSS to the themes core.css.
<code css>
body {background-image:url([[pix:theme|gradient]]);}
</code>

Before we look at how to use your own images within your themes layout files we should first look at how this changes if the image is in a sub directory.

Lets assume gradient.png is located here: '''pix/myimages/gradients/gradient.png'''

The CSS would need to be as follows:
<code css>
body {background-image:url([[pix:theme|myimages/gradients/gradient]]);}
</code>

If you want to refer to an image belonging to a plugin, you can do it like this:

<code css>
body {background-image:url([[pix:quiz|icon]]);}
body {background-image:url([[pix:qtype_ddmarker|grid]]);}
</code>

That refers to mod/quiz/pix/icon.png/gif and question/type/ddmarker/pix/grid.png/gif respectively (or whatever icons you have put in your theme to override these).

===Using your images within your layout files===

To use logo.jpg within the header of the layout file, open the layout file e.g. general.php and find the correct spot to put your logo.

<code php>
....
<div id="page-header" class="clearfix">

<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
echo $OUTPUT->lang_menu();
echo $PAGE->headingmenu;
?></div>
</div>
....
</code>

To achieve this I simply need to add the following line of code:
<code php>
<img src="<?php echo $OUTPUT->pix_url('logo', 'theme'); ?>" alt="" />
</code>
As before, the image's file extension is not needed as Moodle finds it automatically.

Combined the solution is very simple:
<code php>
....
<div id="page-header" class="clearfix">
<img src="<?php echo $OUTPUT->pix_url('logo', 'theme'); ?>" alt="" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
echo $OUTPUT->lang_menu();
echo $PAGE->headingmenu;
?></div>
</div>
....
</code>

The only other thing to consider is how this example would look if logo.jpg was located in a subfolder e.g. '''pix/myimages/logos/logo.jpg'''.

The code for this would be:
<code php>
<img src="<?php echo $OUTPUT->pix_url('myimages/logos/logo', 'theme'); ?>" alt="" />
</code>
'''Note that'theme' above means the word theme, and not the name of your theme'''

==Overriding images in your theme==

Overriding images within your theme can be an important part of creating and/or modifying themes.

As mentioned, there are three main areas for images within Moodle, core, plugins, and themes. Obviously we won't be overriding theme images as we are in a theme and have full control over that already which just leaves core and plugin images that you may want to override.

Within your theme create the following two directories:
; /pix_core/ : This is where your images to override core images will need to be.
; /pix_plugins/ : This is where images to override plugins will need to be.

Next, copy the images that you wish to override into either the pix_core or pix_plugins directory. You need to replicate the directory structure that the images are located in.

The following two examples illustrate how this works for both core and plugin images.

===Overriding core images===
For this example I am going to override the following two images:
# '''moodle/pix/help.gif''' This image is used for all help image icons and is shown throughout Moodle.
# '''moodle/pix/i/info.gif''' This image is used in several places, most notably the front page if the combo list is being displayed.

So first up help.gif. This is the most basic example of overriding an image. Because the image is directly within Moodle's pix directory we can simply place our new help image into our themes pix_core directory. There's nothing more to it!

The second example if not really any more difficult. Because the image is located within the subdirectory '''i''' we must create a sub directory within our pix_core directory into which we will copy our new help image. That is, the image ends up at '''/pix_core/i/info.png''' inside your theme folder. And again done!

You should also note that, as with any other image in Moodle, the extension doesn't matter. If you want to replace help.gif with a help.png you can just put the png into the correct directory. As long as the filename is the same Moodle will find it.

===Overriding plugin images===
This is a little bit more difficult than overriding core images, but not too much so. For this example, let's say I want to override the following two plugin images:
# '''moodle/mod/forum/icon.gif''' This is the icon that is used everywhere for the forum.
# '''moodle/blocks/customblock/activate.png''' This is an icon in a custom block I have installed.

First up, the forum icon. Just as with core images, we need to put the image in the correct directory structure. In this case it is going to be within our theme's pix_plugins directory.

Here we need to create the directory structure between '''/mod/''' and the image, so we need the following structure '''/pix_plugins/mod/forum/''' and into the final forum directory we put our replacement image.

The second example is done in exactly the same way, but with the blocks path. We simply need to put our replacement image in '''/pix_plugins/blocks/customblock/''' and it will automatically be overridden.

When looking for an overriding image the following path is used.

# theme (static)
# themename => mytheme
# area => pix_plugins for plugin images, pix_core for core images, pix for theme images.
# plugin type => booktool for the book tool sub plugin for example.
# plugin name => print for the name of the sub plugin.
# file name => book for the name of the image.

It then searches for the image with the following extensions gif, png, jpg, jpeg in that order.

So you end up with:
<code>
/theme/themename/area/plugintype/pluginname/filename.gif
</code>

==Example: Silkicons theme==
As an example of how this all looks when done I have attached a screen shot of a theme I quickly created using the Silk icon set created by Mark James available at [http://famfamfam.com/lab/icons/silk/ http://famfamfam.com/lab/icons/silk/].

[[Image:Silkicon.theme.screenshot.jpg]]

I have also uploaded the this file to this forum discussion if you would like to check it out for yourself.
[http://moodle.org/mod/forum/discuss.php?d=151581 http://moodle.org/mod/forum/discuss.php?d=151581]

==More information==

* [[Themes 2.0]]
* [[Themes 2.0 creating your first theme]]
* [[Plugins]]
* [http://moodle.org/mod/forum/discuss.php?d=151581 Using images within your themes (and the silk icon theme)]
* [http://moodle.org/mod/forum/discuss.php?d=151581#p689883 choosing images based on the users current language]
* [http://moodle.org/mod/forum/discuss.php?d=157935&parent=691903 how to add a category(categorias) img-bullet]
* [[Replacing_icons_with_CSS3]]

Adding courses and categories to the custom menu

2013-01-10T18:50:18Z

Brianlmerritt: /* How to add "My Courses" to the Custom Menu Bar for Moodle 2.4 */

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.

* [[Themes 2.0]]
* [[Themes 2.0 creating your first theme]]
* [[Themes 2.0 overriding a renderer]]
* [[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 [[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>

==How to add "My Courses" to the Custom Menu Bar for Moodle 2.4==

This adds a nice drop down for logged in users so they can easily see their relevant courses. Note the code below has not been tested on Moodle 2.0-2.3, but you can find working code and instructions on how to add "My Courses" to the custom menu bar for those versions at: [[Themes_2.0_extending_the_custom_menu]]

Below is the Moodle 2.4 custom menu code to add to theme/themename/renderers.php

<code php>
// Add the code below to Moodle 2.4 /theme/themname/renderers.php
<?php>

class theme_themename_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {

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

// Moodle 2.4 doesn't appear to support $mycourses = $this->page->navigation->get('mycourses'); so

if (isloggedin() && !isguestuser() && $mycourses = enrol_get_my_courses(NULL, 'visible DESC, fullname ASC')) { //which does work

$position_mycourses = 8000 ; // lower numbers = higher priority e.g. move this item to the left on the Custom Menu
$branchlabel = get_string('mycourses') ;
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = $position;
$branch = $parent->add($branchlabel, $branchurl, $branchtitle, $branchsort);

foreach ($mycourses as $mycourse) {
$branch->add($mycourse->shortname, new moodle_url('/course/view.php', array('id' => $mycourse->id)), $mycourse->fullname);
}
}
}

//Note to integrate this into the code for adding course and categories at the top of this document page,
//remove this class definition (you only need it once, and change the function name here to:
//
// protected function render_mycourses_custom_menu(custom_menu_item $menu, $position) {
//
//then add a line in the original render_custom_menu function towards the end of it and invoke this function by
//
// $this->render_mycourses_custom_menu($menu, 12000) ;
//
//
//Finally, don't forget to add the language definition for mycourses if that is not already set. Bon chance!!
</code>

Please note, in the comments I did also highlight the bit that doesn't work in Moodle 2.4.

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

Adding courses and categories to the custom menu

2013-01-10T18:47:44Z

Brianlmerritt: Many users want to add "My Courses" to the custom menu, but the code doesn't work for 2.4 so helping users by referencing the 2.0-2.3 code and including new code for 2.4

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.

* [[Themes 2.0]]
* [[Themes 2.0 creating your first theme]]
* [[Themes 2.0 overriding a renderer]]
* [[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 [[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>

==How to add "My Courses" to the Custom Menu Bar for Moodle 2.4==

This adds a nice drop down for logged in users so they can easily see their relevant courses. Note the code below has not been tested on Moodle 2.0-2.3, but you can find working code and instructions on how to add "My Courses" to the custom menu bar for those versions at: [[Themes_2.0_extending_the_custom_menu]]

Below is the Moodle 2.4 custom menu code to add to theme/themename/renderers.php

<code php>
// Add the code below to Moodle 2.4 /theme/themname/renderers.php
<?php>

class theme_themename_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {

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

// Moodle 2.4 doesn't appear to support $mycourses = $this->page->navigation->get('mycourses'); so

if (isloggedin() && !isguestuser() && $mycourses = enrol_get_my_courses(NULL, 'visible DESC, fullname ASC')) { //which does work

$position_mycourses = 8000 ; // lower numbers = higher priority e.g. move this item to the left on the Custom Menu
$branchlabel = get_string('mycourses') ;
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = $position;
$branch = $parent->add($branchlabel, $branchurl, $branchtitle, $branchsort);

foreach ($mycourses as $mycourse) {
$branch->add($mycourse->shortname, new moodle_url('/course/view.php', array('id' => $mycourse->id)), $mycourse->fullname);
}
}
}

//Note to integrate this into the code for adding course and categories at the top of this document page, remove this class definition (you only need it once, and change the function name here to:
//
// protected function render_mycourses_custom_menu(custom_menu_item $menu, $position) {
//
//then add a line in the original render_custom_menu function towards the end of it and invoke this function by
//
// $this->render_mycourses_custom_menu($menu, $position_mycourses) ; //$position_mycourses is the priority for custom menu
//
//Finally, don't forget to add the language definition for mycourses if that is not already set. Bon chance!!
</code>

Please note, in the comments I did also highlight the bit that doesn't work in Moodle 2.4.

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