Cloning a theme: Difference between revisions

Latest revision as of 13:31, 14 July 2021

Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.

See Creating a theme based on boost for an up to date tutorial.

This document describes how to clone a theme from an existing Moodle 2 theme. It assumes you have some understanding of how themes work within Moodle, as well as a basic understanding of XHTML and CSS. Also, because of the rapid development within Moodle, resulting in a number of versions available namely 2.0.x, 2.1.x 2.2.x 2.3.x 2.4.x and soon to be announced Moodle 2.5.x it is important to know that this tutorial is valid for ONLY Moodle Boxxie theme, and as such does not take into account the various other elements you will find in other Moodle versions of themes like Afterburner, Formal White, Sky High, to name but a few. If you are looking to clone one of these themes then checkout my new tutorials. How to clone a Moodle 2.2 theme.

Getting started

Since this is a very easy introduction to creating a custom theme, the first thing to create is a copy of the version of the theme you want to clone. For the purpose of this tutorial, we will be cloning Boxxie, which is one of several Moodle core themes. There are other themes you can 'clone' which are a little harder to do, but once you are familiar with this easy one, you can tackle the harder ones later.

OK...let's get started. From your Moodle theme directory right click on boxxie and then copy and paste back into your Moodle theme directory. You should now have a folder called Copy of boxxie. If you right click this folder you are given the option to Rename it. So let's rename this folder to foxxie (or to whatever name you want to call your cloned theme). It is important to use only lower case letters and underscores.

If you open the foxxie directory you will find several directories, sub-directories and files within it. One of these sub-directories lang/en/ contain a file called theme_boxxie.php which will need to be re-named to theme_foxxie.php. But we shall address this later. For now just familiarise yourself with what you find in the foxxie directory.

These are:

config.php: Where all the theme configurations are made.
/lang/: This directory contains all language sub-directories for other languages if and when you want to add them.
/lang/en/: This sub-directory contains your language files, in this case English.
/lang/en/theme_boxxie.php: This file contains all the language strings for your theme.
/layout/: This directory contains all the layout files for this theme.
/layout/frontpage.php: Layout file for front page.
/layout/general.php: Layout file for all pages other than the front page.
/layout/embedded.php: Layout file for embedded pages.
/style/: This directory contains all the CSS files for this theme.
/style/core.css: Contains all the CSS rules for this theme.
/style/boilerplate.css: Contains all the reset CSS rules for this theme.
/pix/: This directory contains a screen shot of this theme as well as a favicon and any images used in the theme.
/pix/tabs: This contains all the tab images for this theme.

Renaming Elements

The problem when cloning a theme is that you need to rename all those instances where the theme name, in this case boxxie, occurs. The first place to look is config.php, where you need to change the theme name.

$THEME->name = 'boxxie';

////////////////////////////////////////////////////
// Name of the theme. Most likely the name of
// the directory in which this file resides.
////////////////////////////////////////////////////

The next place to look, as mentioned above, is lang/en/theme_boxxie.php. This file, as well as needing to be renamed, also needs some of its content renaming too. So before we forget, let's right click on this file and rename it theme_foxxie.php before we open it.

Language Strings

When you open theme_foxxie.php the first thing you will see are the credits for the theme.

/**
 * Strings for component 'theme_boxxie', language 'en', branch 'MOODLE_20_STABLE'
 *
 * @package   moodlecore
 * @copyright 2010 Patrick Malley
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

Here you will need to change the reference from boxxie to foxxie, you can leave the rest of this as it is.

The next things you will find in this file are what are known as the language strings. These are used for any customised words or phrases used in a theme. And because this is in the foxxie/lang/en/ directory all the $strings are in English. But if you wanted to add some foreign words and phrases for whenever a user switched languages, you just need to create a new sub-directory in the foxxie/lang/ directory for the language files you need to add there, and then copy and paste this file to that new sub-directory. For example: foxxie/lang/it/theme_foxxie.php (where it is the code which represents the Italian language). We will explore the Language aspect of themes in another Moodle Doc. So let's just concentrate on the changes we need to make to rest of the contents of theme_foxxie.php.

$string['pluginname'] = 'Boxxie';
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';

In the $string section above, the only thing you need to change here is the pluginname from boxxie to foxxie.

In this next section, the choosereadme, which is written in XHTML and is the contents of the page that you will see when selecting Foxxie in the Theme Selector. However, you are advised to read what is actually written there and change it accordingly, renaming 'Boxxie' to 'Foxxie', and changing the contents of this part to suit yourself. You might not want to keep all that is written here. You could actually condense it, but that's up to you. Just as long as you give credit, where credit is due, to the original theme designer by stating something on similar lines to what I have written below.

$string['choosereadme'] = 'Foxxie is a customised Moodle theme
by Mary Evans based on the original Boxxie theme by Patrick Malley';

Now open version.php file and change $plugin->component

$plugin->component = 'theme_foxxie';

Recipe for the Impatient

For those who want a minimal set of instructions to semi-blindly blast through this:

1. Copy [moodleroot]/theme/boxxie to [moodleroot]/theme/foxxie

2. Rename [moodleroot]/theme/foxxie/lang/en/theme_boxxie.php to [moodleroot]/theme/foxxie/lang/en/theme_foxxie.php

3. In [moodleroot]/theme/foxxie/lang/en/theme_foxxie.php, replace any instances of "boxxie" with "foxxie", likewise for "Boxxie" and "Foxxie".

4. Edit [moodleroot]/theme/foxxie/config.php to replace instance(s) of "boxxie" with "foxxie".

5. Edit [moodleroot]/theme/foxxie/version.php to replace instance(s) of "boxxie" with "foxxie".

Appendix

Please Note: All theme names, directory names, and file names MUST be in lowercase.

@@ Line 1: / Line 1: @@
-{{Template:Themes}}{{Moodle 2.0}}This document describes how to clone a theme from an existing Moodle 2.0. theme. It assumes you have some understanding of how themes work within Moodle, as well as a basic understanding of HTML and CSS.
+{{obsolete}}
+See [[Creating a theme based on boost]] for an up to date tutorial.
+This document describes how to clone a theme from an existing Moodle 2 theme. It assumes you have some understanding of how themes work within Moodle, as well as a basic understanding of XHTML and CSS. Also, because of the rapid development within Moodle, resulting in a number of versions available namely 2.0.x, 2.1.x 2.2.x 2.3.x 2.4.x and soon to be announced Moodle 2.5.x it is important to know that this tutorial is valid for ONLY Moodle Boxxie theme, and as such does not take into account the various other elements you will find in other Moodle versions of themes like Afterburner, Formal White, Sky High, to name but a few. If you are looking to clone one of these themes then checkout my new tutorials. [https://docs.moodle.org/dev/Themes_2.2_how_to_clone_a_Moodle_2.2_theme How to clone a Moodle 2.2 theme].
 ==Getting started==
-The first thing to create is a copy of the theme folder, of the theme, you want to clone. For the purpose of this tutorial, we will be cloning '''Boxxie''', which is one of several Moodle '''core''' themes.
+Since this is a very easy introduction to creating a custom theme, the first thing to create is a copy of the version of the theme you want to clone. For the purpose of this tutorial, we will be cloning '''Boxxie''', which is one of several Moodle '''core''' themes. There are other themes you can 'clone' which are a little harder to do, but once you are familiar with this easy one, you can tackle the harder ones later.
-From your Moodle '''theme''' directory '''right click''' on '''boxxie''' and then '''''copy''' and  '''paste''''' back into your Moodle '''theme''' directory. You should now have a folder called '''Copy of boxxie'''. If you '''right click''' this folder you are given the option to '''Rename''' it. So let's rename this folder to '''foxxie''' (or to whatever name you want to call your '''cloned''' theme).
+OK...let's get started. From your Moodle '''theme''' directory '''right click''' on '''boxxie''' and then '''''copy''' and  '''paste''''' back into your Moodle '''theme''' directory. You should now have a folder called '''Copy of boxxie'''. If you '''right click''' this folder you are given the option to '''Rename''' it. So let's rename this folder to '''foxxie''' (or to whatever name you want to call your '''cloned''' theme).  It is important to use only lower case letters and underscores.
-If you open the '''foxxie''' directory you will find several directories, sub-directories and files within it. One of these sub-directories '''''lang/en/''''' contain a file '''theme_boxxie.php''' which will need to be re-named. But we shall address this later. For now just familiarise yourself with what you find in the '''foxxie''' directory.
+If you open the '''foxxie''' directory you will find several directories, sub-directories and files within it. One of these sub-directories '''''lang/en/''''' contain a file called '''theme_boxxie.php''' which will need to be re-named to '''theme_foxxie.php'''. But we shall address this later. For now just familiarise yourself with what you find in the '''foxxie''' directory.
 These are:
-; config.php :  Where all the theme settings are.
+; config.php :  Where all the theme configurations are made.
-; /lang/ : This directory contains all language sub-directories.
+; /lang/ : This directory contains all language sub-directories for other languages if and when you want to add them.
 ; /lang/en/ : This sub-directory contains your language files, in this case ''English''.
 ; /lang/en/theme_boxxie.php : This file contains all the language strings for your theme.
 ; /layout/ : This directory contains all the layout files for this theme.
 ; /layout/frontpage.php : Layout file for front page.
-; /layout/general.php : Layout file for general pages.
+; /layout/general.php : Layout file for all pages other than the front page.
 ; /layout/embedded.php : Layout file for embedded pages.
 ; /style/ : This directory contains all the CSS files for this theme.
@@ Line 24: / Line 29: @@
 ; /pix/tabs : This contains all the tab images for this theme.
-==Re-naming some elements==
+==Renaming Elements==
 The problem when '''cloning''' a theme is that you need to rename all those instances where the theme name, in this case '''boxxie''', occurs. The first place to look is '''config.php''', where you need to change the theme name.
-<code php>
+<syntaxhighlight lang="php">
 $THEME->name = 'boxxie';
@@ Line 34: / Line 39: @@
 // the directory in which this file resides.
 ////////////////////////////////////////////////////
-</code>
+</syntaxhighlight>
 The next place to look, as mentioned above, is '''lang/en/theme_boxxie.php'''. This file, as well as needing to be renamed, also needs some of its content renaming too. So before we forget, let's '''right click''' on this file and '''rename''' it '''theme_foxxie.php''' before we open it.
@@ Line 40: / Line 45: @@
 === Language Strings ===
-When you open theme_foxxie.php the first thing you will see are the '''credits''' for the theme.
+When you open '''theme_foxxie.php''' the first thing you will see are the '''credits''' for the theme.
-<code php>
+<syntaxhighlight lang="php">
 /**
   * Strings for component 'theme_boxxie', language 'en', branch 'MOODLE_20_STABLE'
@@ Line 49: / Line 54: @@
   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
   */
-</code>
+</syntaxhighlight>
-Here you will need to change the reference to to '''boxxie''' to '''foxxie''', you can leave the rest of this as it is.
+Here you will need to change the reference from '''boxxie''' to '''foxxie''', you can leave the rest of this as it is.
-The next things you will find in this file are what are known as the '''language strings'''. These are used for any customised '''''words'' or ''phrases''''' used in this theme. And because this is in the '''foxxie/lang/en/''' directory all the $strings are in English. But if you wanted to add some foreign words and phrases for whenever a user switched languages, you just need to create a new sub-directory in the '''foxxie/lang/''' directory for the language files you need to add there, and then copy and paste this file to that new sub-directory. For example: '''foxxie/lang/it/theme_foxxie.php''' (where '''it''' is the code which represents the Italian language). We will explore the Language aspect of themes in another Moodle Doc. So let's just concentrate on the changes we need to make to rest of the contents of '''theme_foxxie.php'''.
+The next things you will find in this file are what are known as the '''language strings'''. These are used for any customised '''''words'' or ''phrases''''' used in a theme. And because this is in the '''foxxie/lang/en/''' directory all the $strings are in English. But if you wanted to add some foreign words and phrases for whenever a user switched languages, you just need to create a new sub-directory in the '''foxxie/lang/''' directory for the language files you need to add there, and then copy and paste this file to that new sub-directory. For example: '''foxxie/lang/it/theme_foxxie.php''' (where '''it''' is the code which represents the Italian language). We will explore the Language aspect of themes in another Moodle Doc. So let's just concentrate on the changes we need to make to rest of the contents of '''theme_foxxie.php'''.
-<code php>
+<syntaxhighlight lang="php">
 $string['pluginname'] = 'Boxxie';
 $string['region-side-post'] = 'Right';
 $string['region-side-pre'] = 'Left';
-</code>
+</syntaxhighlight>
-In this first section above, the only thing you need to change here is the works '''boxxie'''.
+In the $string section above, the only thing you need to change here is the '''pluginname''' from '''boxxie''' to '''foxxie'''.
-In this next section, the '''choosereadme''' however, you need to read what is there and change it accordingly, renaming 'boxxie' to 'foxxie', and changing the contents of this part to suit youself. You might not want to keep all that is written here. You could actually condense it, but that's up to you. Just as long as you give due credit, where credit is due, to the original theme designer in the '''credits''' section by stating something on the lines that, '''''Foxxie is a customised Moodle theme based on the original Boxxie theme by Patrick Malley.'''''
+In this next section, the '''choosereadme''', which is written in XHTML and is the contents of the page that you will see when selecting '''Foxxie''' in the Theme Selector. However, you are advised to read what is actually written there and change it accordingly, renaming 'Boxxie' to 'Foxxie', and changing the contents of this part to suit yourself. You might not want to keep all that is written here. You could actually condense it, but that's up to you. Just as long as you give credit, where credit is due, to the original theme designer by stating something on similar lines to what I have written below.
-<code php>
+<syntaxhighlight lang="php">
-$string['choosereadme'] = '<div class="clearfix"><div class="theme_screenshot"><h2>Boxxie</h2><img src="boxxie/pix/screenshot.jpg" /><h3>Theme Discussion Forum:</h3><p><a href="http://moodle.org/mod/forum/view.php?id=46">http://moodle.org/mod/forum/view.php?id=46</a></p><h3>Theme Credits</h3><p><a href="https://docs.moodle.org/en/Theme_credits">https://docs.moodle.org/en/Theme_credits</a></p><h3>Theme Documentation:</h3><p><a href="https://docs.moodle.org/en/Themes">https://docs.moodle.org/en/Themes</a></p><h3>Report a bug:</h3><p><a href="http://tracker.moodle.org">http://tracker.moodle.org</a></p></div><div class="theme_description"><h2>About</h2><p>Boxxie is a fluid-width, three-column theme for Moodle 2.0.<h2>Tweaks</h2><p>This theme is built upon both Base and Canvas, two parent themes included in the Moodle core. If you want to modify this theme, we recommend that you first duplicate it then rename it before making your changes. This will prevent your customized theme from being overwritten by future Moodle upgrades, and you\'ll still have the original files if you make a mess. More information on modifying themes can be found in the <a href="https://docs.moodle.org/en/Theme">MoodleDocs</a>.</p><h2>Credits</h2><p>This theme was coded and is maintained by Patrick Malley. He can be contacted by email at contact@newschoollearning.com. </p>
+$string['choosereadme'] = 'Foxxie is a customised Moodle theme
-<h3>License</h3><p>This, and all other themes included in the Moodle core, are licensed under the <a href="http://www.gnu.org/licenses/gpl.html">GNU General Public License</a>.</div></div>';</code>
+by Mary Evans based on the original Boxxie theme by Patrick Malley';
+</syntaxhighlight>
-And basically that's it as far as this theme is concerned. However there are some themes which contain far more files and directories, so be sure to check those thoroughly.
+Now open version.php file and change $plugin->component
+<syntaxhighlight lang="php">
+$plugin->component = 'theme_foxxie';
+</syntaxhighlight>
+==Recipe for the Impatient==
+For those who want a minimal set of instructions to semi-blindly blast through this:
+'''1.''' Copy ''[moodleroot]/theme/boxxie'' to ''[moodleroot]/theme/foxxie''
+'''2.''' Rename ''[moodleroot]/theme/foxxie/lang/en/theme_boxxie.php'' to ''[moodleroot]/theme/foxxie/lang/en/theme_foxxie.php''
+'''3.''' In ''[moodleroot]/theme/foxxie/lang/en/theme_foxxie.php'', replace any instances of "boxxie" with "foxxie", likewise for "Boxxie" and "Foxxie".
+'''4.''' Edit ''[moodleroot]/theme/foxxie/config.php'' to replace instance(s) of "boxxie" with "foxxie".
+'''5.''' Edit ''[moodleroot]/theme/foxxie/version.php'' to replace instance(s) of "boxxie" with "foxxie".
+==Appendix==
+Please Note: All theme names, directory names, and file names MUST be in lowercase.
 ==See also==
-* [[Themes 2.0 FAQ]]
-[[Category:Themes]]
+* [http://youtu.be/ctEYt_z2bNE Cloning the Clean Theme]  MoodleBites video on YouTube
+* [[Making a horizontal dock]] - Modifying the dock to make it horizontal.
+* [[Styling and customising the dock]] - How to style and customise the dock.
+* [[Adding theme upgrade code]]
+* [[Theme changes in 2.0]]
+* [[jQuery]]
+[[es:Clonar un tema]]