Images and icons in themes
One of the theme features is the ability to override any of the standard images within Moodle when your theme is in use. At this point, let's explore how to utilize your own images within your theme and how to override the images being used by Moodle. So first up a bit about images within Moodle:
- Images you want to use within your theme must to be located within your theme's
pix
directory. - You can use sub directories within the
pix
directory of your theme. - Images used by Moodle's core are located within the
pix
directory of Moodle. - All plugins should store their images within their own
pix
directory.
The following section assumes that there are two image files in the pix
directory of a theme named yourthemename
:
/theme/yourthemename/pix/imageone.svg
/theme/yourthemename/pix/subdir/imagetwo.png
The first image is an SVG, and the second a PNG located in a subdirectory.
Use images in templates
The following example illustrates how to make use of these images within your layout file so they can be inserted in your layout template.
$templatecontext = [
$imageone => $OUTPUT->pix_url('imageone', 'theme'),
$imagetwo => $OUTPUT->pix_url('subdir/imagetwo', 'theme'),
];
echo $OUTPUT->render_from_template('theme_yourtheme/somelayout', $templatecontext);
A method of Moodle's output library is utilized to generate the URL to the image. It's not too important how that function works, but it is important that it's used, as it's what allows images within Moodle to be overridden.
DO NOT include the image file extension. Moodle will work it out automatically and it will not work if you do include it.
Use images in CSS
The following is how you would use the images from within CSS/SCSS as background images.
.divone {
background-image: url([[pix:theme|imageone]]);
}
.divtwo {
background-image: url([[pix:theme|subdir/imagetwo]]);
}
A placeholder is used within the CSS to allow use of a pix icon. During the CSS/SCSS compilation, these placeholders are converted into a URL which the browser can fetch and serve.
Notice that the image file extension included. The reason for this leads us into the next topic, how to override images.
Override images
From within a theme you can very easily override any standard image within Moodle by simply adding the replacement image to the theme's pix directory in the same sub directory structure as it is in Moodle. So, for instance, if there is a need to override the following images:
/pix/moodlelogo.png
/pix/i/user.svg
/mod/chat/pix/monologo.svg
Simply add the replacement images to the theme in the following locations:
/theme/themename/pix_core/moodlelogo.png
/theme/themename/pix_core/i/user.svg
/theme/themename/pix_plugins/mod/chat/monologo.svg
A pix_core
directory has been created in the theme to store the replacement images. For a specific activity module like chat, the directory pix_plugins/mod/chat
is needed. This directory is pix_plugins
and then the plugin type (mod
) and then the plugin name (chat
).
Another noteworthy aspect is that Moodle not only searches for replacements of the same image type (svg, png, jpg, gif, and so on) but also replacements in any image format. This is why the image file extension was never specified when working with our images above. This means that the following would also work:
/theme/themename/pix_core/moodlelogo.svg
/theme/themename/pix_core/i/user.jpg
For a more detailed description of how this all works see the page on Using images in a theme.