Using images in a theme

A little background

Moodle has a standard way 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 performance caching system to obtain the best possible performance.

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

"e" - Editor-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 theme's directory.

Lets assume you have two images, gradient.png and logo.jpg. Copy both files to your theme's 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 pattern when using your 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 gradient.png as the background for our pages, add the following line of CSS to the theme's core.css.

body {background-image:url([[pix:theme|gradient]]);}

Before we look at how to use your own images within your theme's 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([[pix:theme|myimages/gradients/gradient]]);}

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

body {background-image:url([[pix:quiz|icon]]);}
body {background-image:url([[pix:qtype_ddmarker|grid]]);}

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

body {background-image:url([[pix:block_customblock|grid]]);}

That refers to blocks/customblock/pix/grid.png/gif/jpg (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 a layout php file or layout mustache template you need to add the url for the image to the template context and then include an image tag in the template using the source from the context.

Images:

/pix/logo.jpg
/pix/myimages/logos/logo.png

theme/yourtheme/layout/somelayout.php

...
$templatecontext = [
...
'imageone' => $OUTPUT->image_url('logo', 'theme'),
'imagetwo' => $OUTPUT->image_url('myimages/logos/logo', 'theme'),
...
];

echo $OUTPUT->render_from_template('theme_yourtheme/somelayout', $templatecontext);

theme/yourtheme/templates/somelayout.mustache

...
<img src="{{{imageone}}}" alt="Please give your image alt text or set the role to presentation" width="50" height="50">
<img src="{{{imagetwo}}}" alt="Please give your image alt text or set the role to presentation" width="50" height="50">
...

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 theme's 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:

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.

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. The correct path must use the plugin type Frankenstyle prefix and the plugin name.

For the examples above the paths to override the plugin images will be:

1. pix_plugins/mod/forum/
2. pix_plugins/block/customblock/

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

1. theme (static)
2. themename => mytheme
3. area => pix_plugins for plugin images, pix_core for core images, pix for theme images.
4. plugin type => booktool for the book tool sub plugin for example.
5. plugin name => print for the name of the sub plugin.
6. 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:

/theme/themename/area/plugintype/pluginname/filename.gif

See also

• Plugins
• Adding Images to your Theme MoodleBites video on YouTube

Using Moodle forum discussions:

• Using images within your themes (and the silk icon theme)
• choosing images based on the users current language
• how to add a category(categorias) img-bullet