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 hundreds of countries around the world, there are thousands of installations, millions of end users, 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 of 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 a sub directory 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 a 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.

More information

Themes 2.0

Themes 2.0 creating your first theme

Plugins