Development:Themes 2.0 How to use images within your theme

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

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

Here we are looking at introducing new images for use within your theme. These will be things such as background images, or logos and can be used in both CSS and within the HTML of your theme.

The first thing to do is create a pix directory within your themes directory. This is where all of your own images are going to live.

For the purpose of this document lets assume you have two images that you want to use.

Copy gradient.png into your themes pix directory.
Copy logo.jpg into your themes pix directory

The plan here is to use gradient.png as the background image for your theme, this we will do in CSS. After that we will put logo.jpg into the header for your theme which we will do in your theme's layout file.

Using your images within CSS

Using images within CSS is very easy. As you're all undoubtedly aware 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. Well 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. This is how we are able to add our images into our themes CSS and be sure that they are always correct. You should note the following things about this patter when using you 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, it is just the filename you don't put the extension Moodle works that out.

So in our case we want to use background.png as the background of for our pages. To do this we would add the following line of CSS to our themes core.css. body {background-image:url(gradient);}

As that's it, however 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

Our CSS would need to be as follows: body {background-image:url(myimages/gradients/gradient);}

Using your images within you layout files

The second thing we wanted to do was use logo.jpg within the header of our layout file. This is completely different to using images within CSS as the layout files are PHP not CSS. However I feel this is even easier.

So open up your layout file, for me standard.php and find the correct spot to put your logo. I'm going to insert it as shown below: ....


    <?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="" /> Just like with the CSS example above you should not that I do not need to add the image's file extension. 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 look at at this point is how this example would look if logo.jpg was located in a sub folder. Like the previous example lets assume logo.jpg is located here: pix/myimages/logos/logo.jpg The code for this would be: <img src="<?php echo $OUTPUT->pix_url('myimages/logos/logo', 'theme'); ?>" alt="" />

And that's it! We've now looked at how to use your own images within your theme in both CSS and layout files.

Overriding images in your theme

Overriding images within your theme can be an important part of creating and/or modifying themes. At some point or another you are undoubtedly going to find images within Moodle that you either don't like or do not work with your theme (such as if you have a dark theme).

Luckily it is very easy to override images within a theme. You just need to know a little bit about them.

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.

Now it's not just a matter of simply dumping 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. 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.

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

Development:Themes 2.0

Development:Themes 2.0 creating your first theme

Development:Plugins

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

Documentation