Using images in a theme

Moodle 2.0

A little background

Moodle 2.0 has introduced a new `better` 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 are lower are gone from Moodle 2.0 and have been replaced by this new system.

Before we start

1. Make sure you have a theme and images to work with, one that you have a backup of just in case.
2. Take note of your theme's main layout file e.g. standard.php.
3. Take note of your theme's main CSS file e.g. core.css.
4. 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 log, 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.

[[pix:theme|path/to/image/imagename]]

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 patter when using you own images within CSS:

1. The bits in black don't change
2. 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.
3. 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. body {background-image:url(gradient);}

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: body {background-image:url(myimages/gradients/gradient);}

Using your images within you layout files

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

....

<?php echo $PAGE->heading ?>

<?php

       echo $OUTPUT->login_info();
       echo $OUTPUT->lang_menu();
       echo $PAGE->headingmenu;

 ?>

....

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

Combined the solution is very simple: ....

   <img src="<?php echo $OUTPUT->pix_url('logo', 'theme'); ?>" alt="" />

<?php echo $PAGE->heading ?>

<?php

       echo $OUTPUT->login_info();
       echo $OUTPUT->lang_menu();
       echo $PAGE->headingmenu;

 ?>

....

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: <img src="<?php echo $OUTPUT->pix_url('myimages/logos/logo', 'theme'); ?>" alt="" />

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:

1. moodle/pix/help.gif This image is used for all help image icons and is shown throughout Moodle.
2. 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. 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:

1. moodle/mod/forum/icon.gif This is the icon that is used everywhere for the forum.
2. 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.

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

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

More information

Themes 2.0

Themes 2.0 creating your first theme

Plugins

http://moodle.org/mod/forum/discuss.php?d=151581