Using images in a theme

Moodle 2.0

Hello, this document looks at how to use images within your own theme. It addresses the two main aspects to using images: first adding new images to your theme, and second how to override existing images within Moodle.

A little background

Moodle 2.0 has introduced a new `better` method of making use of images within its pages. For you as a themer this new method ensures that you can always take full control over what images are being used, can easily introduce new images into your themes, and when possible ensures the images you use are passed through Moodle's new performance caching system so that those who use your theme will get the best performance possible.

Those of you who are familiar with Moodle 1.9 or lower will more than likely be familiar with both $CFG->themewww and custom pix. These are both gone from Moodle 2.0 and have been replaced by this new system which is a little like custom pix. Take the time to learn this new system and we are sure you will appreciate it.

Why use a special system for images

For those of you who are new to Moodle you are probably asking why we have created a special system for images? The answer can be summed up by two concepts diversity and flexibility.

Diversity

First up diversity, Moodle is used in hundreds of countries around the world, there are thousands of installations, millions of end users, and every single installation out there is going to be unique in some way. Add to that the brilliant efforts of the community in coming up with plugins, customisations, hacks, and support products and you require a system that is truly diverse.

Images need to work no matter what the URL or URI of the installation is, whether it is running over http or https, and whether it is coming from Moodles core image stock or from a plugin or customisation.

Other things such as performance also need to be taken into consideration, some people use Moodle on local fibre networks, some over broadband, some still use dial up. Moodles system is designed to make sure we deliver images with the best performance possible.

Flexibility

The other key concept in the image system is flexibility. This is there for all the themers out there, and there are a lot. Not only do we want to be able to serve images intelligently we also want them to be over-rideable so that the people who are making the look and feel that the millions of end users will experience can create the solution they desire.

It shouldn't matter where the image is coming from they should be able to override it and use there own. This system aims to achieve just that.

However there will be images that can not be overridden, old code being the culprit in this case, but do not fret we have put a great deal of effort into making sure that all core code uses this new system and while there will be places we have missed hopefully they are few and far between.

Before we start

There's not too much to this at the end of the day however a little preparation at this point will ensure I don't have to repeat instructions later on :). So:

1. Make sure you have a theme to work with, one that you have a backup of just encase.
2. Have the images you want to use ready to go.
3. Take note of your themes main layout file, for the purpose of this document I will assume it is standard.php.
4. Take note of your themes main CSS file, I'm going to use core.css for this document.
5. Turn on Theme designer mode because if its off you won't see any of your changes!

And that's it!

Image locations within Moodle

This is most pertinent to those looking to override images as in order to override the image you must understand where the image is coming from. If you can't find it you can't override it. Within Moodle there are three main areas in which images will be located:

core

These are images that are stored within Moodle's pix directory moodle/pix and are used all throughout Moodle.

plugin

Images used by plugins are stored somewhere within the plugin's individual directory. e.g. mod/forum/* or blocks/navigation/*

theme

This is the most relevant to you as a themer, images for theme's will be stored in the pix subdirectory of a theme.

So lets look at each of the main areas:

Core images

Core images as mentioned above are images that are used all throughout Moodle. They are located within Moodle's pix directory and for many of them within a subdirectory of the main pix directory.

If you don't know where to find an image then this is probably the best place to start.

If you open the pix directory within your file explorer you will see that there are half a dozen sub directories all of which contain many images. The following is a list of the directories you will find in there an what each contains.

• a Contains a handful of 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

Keep in mind when overriding these icons that they get used all over the place, don't assume the one place you are seeing them is the only place they are used.

Plugin images

Plugin images are images that are used been used by specific plugins and will always be located within the specific plugins directory. There are dozens of different plugin types within Moodle. However you will find that most of the time only the following will use images:

• Modules: Activities and resources located in the /mod/ directory
• Blocks: Located in the /blocks/ directory

The plugin types page contains a full list of plugin types and links off to information on each.

Theme images

These are images that are used solely by themes and is what you will be using when you read the section on adding new images to your theme.

Adding new images to your theme

Here we are looking at introducing a 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 three images that you want to use.

1. Copy gradient.png into your themes pix directory.
2. 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:

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, 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: <?php echo $OUTPUT->pix_url('logo', 'theme'); ?> Just like with the CSS example above you should not that I do not need to add the image files extension. Moodle finds it automatically.

Combined the solution is very simple: ....

   <?php echo $OUTPUT->pix_url('logo', 'theme'); ?>

<?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. So like the previous example lets assume logo.jpg is located here: pix/myimages/logos/logo.jpg The code for this would be: <?php echo $OUTPUT->pix_url('myimages/logos/logo', 'theme'); ?>

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

Overriding images in you 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 don't 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 you theme create the following two directories:

/pix_core/

This is where our images to override core images will end up.

/pix_plugins/

Here is where images to override plugins will need to go.

Now it's not as 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 a 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 all 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 like with any other image in Moodle the extension doesn't matter. If you want to replace help.gif with a png file you can just put the png into the correct directory. As long as the filename is the same Moodle will find it.

Overriding a plugin images

This is a little bit more difficult than overriding core images but not by very much. For this example lets 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 like with core images we need to put the image in the correct directory structure. In this case it is going to be within our themes pix_plugins directory.

Here we need to create the directory structure after from /mod/ to 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 exactly the same but with the blocks path. We simply need to put our replacement image in /pix_plugins/blocks/customblock/ and it will automatically be overriden.

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