Edited by Christopher Douce, Wednesday, 21 Jul 2010, 18:27
This post is about the journey that I followed trying to understand Moodle Themes. Moodle Themes are pieces of programming magic that change the visual appearance of your Moodle installation.
If you download Moodle and play around with it, you might eventually arrive at a decision that it might be useful within your institution. You might hold a meeting with senior management where you may say, 'I think it's a good idea if we try to use this thing call Moodle to host some of our courses'. After answering some difficult questions about maintenance and development costs, your managers might say, 'okay, you've convinced us... let's give it a go, I'll give you a budget'
Other than figuring out which operating system and database to use and where (and how) your instance of Moodle is to be hosted, one of the first development activities you will have to do is make sure that your Moodle system is 'on brand', i.e. it's visual appearance should reflect the institution that you work for.
This is pretty much what I have to do. I have to try and make my 'vanilla' (unmodified) version of Moodle blend in with a set of existing web pages that have been built as a part of a research project I'm working on. Other development teams within my university have already done something similar with their production version of Moodle, but I need to tackle this problem myself.
I start with a couple of questions: what makes up a theme and how might you go about changing one or maybe even making a new one?
Resources galore
Before I can answer these questions I needed to find something to read, and it didn't take a lot of browsing to find a number of potentially useful resources.
The first page that I discovered was a link to over one hundred different themes thanks to the Database of Moodle Themes. Perhaps I shouldn't be so surprised given the number of Moodle installations that are out there in the world.
The Themes documentation link (for a Themes novice) seems to be the most useful. One of the sections says that themes can be delivered in zip files. You download them, unzip them and place the contents in the /moodle/theme directory, and then click on some admin tools to activate it. This sounds almost too easy!
Towards Code
Being someone who likes to view code I thought it might be useful to look at some of the magic that makes Moodle themes work. To do this, I chose a random theme from the themes database and unzipped a folder to my desktop. To begin to make sense of it properly, I felt that it might be a good idea to compare this random theme against one that already existed. This made me answer, 'which theme is used by default?'
To answer this question, I logged onto my local instance of Moodle (which was running on my local machine, localhost) as an administrator. After struggling to remember my username and password, I clicked on the Administration link, followed Appearance, Themes and then on the Theme Selector link (because I couldn't really make sense of the Theme Settings options).
I quite like the Theme Selector page. It presents all the different themes that have been installed. The current theme that is selected is highlighted by a black square. The one that was selected by default (in the case of my installation - I cannot remember whether I changed it) was named standardwhite.
I delve into the Moodle code area, take a copy of standardwhite and placed it alongside the one I have randomly downloaded and started poking around.
Looking at code
I noticed similarities and differences. The similarities are that some of the filenames are the same. I see two PHP files, styles and config, followed by two html files, header and footer. There seems to be a CSS file (Wikipedia) in both themes (but the downloaded theme contains a few more than the default theme). I also notice a graphics file called gradient in the default theme (which is a jpg), and a png graphics file in the other one. A big difference lies was that the theme I have downloaded contains a directory which seems to contain a bunch of graphic files.
Before deciding I'm terribly confused, I decide to do one more thing: open up both of the PHP files to see what they contain.
In a config script, I see assignments to a variable called $THEME. Different attributes appear to do different kinds of magic. Looking in the styles script, a comment tells me that 'there should be no need to modify this file'. It seems to do something that relates to the presentation of a CSS file. That is good enough for me!
I have a quick peek into the header and the footer html files. It looks like these are templates (of some kind) that are filled out using the contents of some PHP variables. Obviously the pages that the Moodle code creates have a pretty well defined structure, and presumably this structure is documented somewhere. This is perhaps something I might need to remember later.
Return to the documentation
At this point, I roughly (think) I know what a Theme comprises: some magic scripts which define some variables (and some other stuff), some header and footer scripts which look at bit like templates, a CSS file of some kind, perhaps a graphic (which could be used by the CSS file?) and maybe a bunch of graphics that replace those that are used in Moodle by default.
If this is my current understanding, can I now find the documentation easier to understand?
I soon uncover two further pages: Make your own Theme and Creating a Custom Theme (the first link seems to be easier to understand). A couple of clicks takes me to a documentation page called Theme config file which goes some way to explaining the variables that I have touched upon above.
The final comment in the Creating a Custom Theme page was instructive. Other than saying that you can't change everything, if you want to make your site look like an existing site, it might be a good idea to make use of a tool called Firebug which is a plug in for your Firefox browser.
With Firebug, you can browse to a web page of your choice and uncover what CSS definitions have been used to build its visual appearance. I've used Firebug before, and mentioning that it is a good tool is certainly a good piece of advice. The Moodle developers have also been kind enough to prepare a CSS FAQ which is certainly worth a look.
Although I could have tried to create a new theme from scratch, I'm in a lucky position since one of my colleagues has already created a customised theme for a custom instance of Moodle.
Towards testing things out
To test things out, I copy of my customised theme into my local 'themes' directory and hit refresh on my browser. I then select my newly installed theme and everything starts to go wrong. The action of selecting a theme seemed to have rendered my local copy of Moodle useless since only a tiny fraction of a HTML page is created (which I see by viewing the code the browser receives).
A problem seems to have been created since the version of Moodle that I am using and the structure of the theme that I have transferred are not completely compatible with each other. I need to go back to my default theme! But how do I do this? Where are the theme settings held?
My first guess is in the database. I open up a front end to the MySQL database that is running on my PC, using a tool called SqlYog. I eyeball the contents of the database to see if there's anything I can use. I discover a 'config' table, but this doesn't tell me much. I did, however, discover that there is a theme setting within individual courses as well as individual users.
I turn my attention towards the code by first looking at the code within the themes directory and I soon find myself fruitlessly searching through different libraries. Finding a simple answer may necessitate spending quite a bit of time.
To get things working again, you sometimes have to cheat. I renamed my theme to something totally different and refreshed my Moodle page. Moodle then had no choice but to return to its default setting (which was, again, 'standardwhite').
Incrementally merging
I have two themes: one theme that I want to use but doesn't work (because it has been modified for a customised version of Moodle), and another theme that does work which I don't want to use. When I'm faced with this situation, I try to get 'code to speak to me' by incrementally taking the one that works and making it look like the one that doesn't work. I find I can really understand stuff when things stop working!
I begin by looking at the files and then the contents of the files. The first thing that strikes me is that the header and footer files are quite different. There seems to be quite a bit more happening in the customised theme when compared to the standard theme. A step at a time I move files across and test, beginning with the favicon, then the config file, and finally the pix's. I discover that both themes require the use of a CSS file that is contained within the standard theme directory.
The effect of moving files around seems to produce, more or less, what I was after. The interactive 'side blocks' (particularly the show/hide buttons) are not presented as they should, but further searching reveals a magic variable, allowuserblockhiding that can be used to control this functionality.
Moodle version 2
A question to complete this post is: what is the situation regarding Moodle version 2.0? This is a development that I have heard about for some time, but I have not heard recent any announcements regaring its expected release. After a quick search, I reacquaint myself with something called the Moodle Roadmap.
This appears to state that there will be a beta release of V2 by the end of 2009, followed by some months of testing before a final release. Judging by the planning document, there appears to be quite a lot more coding to do (nearly four hundred days of development time to go, so we should expect some delays).
I appreciate that giving opinion is certainly a lot easier than giving code, so I hope that Moodlers who read this section will forgive me. I personally hope that the code for the next version is a lot cleaner. Since the developers are forced to move to PHP version 5, I hope they will choose to adopt its object-oriented features which can help developers to form clearer (less leaky) abstractions.
In a perfect world, developers should be able to look at a screenful of code and be able to describe, more or less, what that section of code does without having to look at other code (providing, of course, they more or less have an understanding of what the product does). From what I have seen so far in version 1.9, there is a long way to go to, but I'm certainly looking forward to learning how things have moved on in version 2.0.
Wrap-up
It's great that the developers of Moodle have designed it in such a way that it is 'themeable' (if there is such a word). In some respects, I was surprised to discover things were not as difficult as I had expected. Whilst, in some ways, going directly to the code and looking what is there may be a daunting challenge, it is one that I certainly recommend doing.
There's a whole lot more to the issue of Moodle themes. I haven't touched upon the structure of Moodle pages and how they relate to elements in stylesheets, for example. I'll leave this challenge for another day!
Understanding Moodle Themes
This post is about the journey that I followed trying to understand Moodle Themes. Moodle Themes are pieces of programming magic that change the visual appearance of your Moodle installation.
If you download Moodle and play around with it, you might eventually arrive at a decision that it might be useful within your institution. You might hold a meeting with senior management where you may say, 'I think it's a good idea if we try to use this thing call Moodle to host some of our courses'. After answering some difficult questions about maintenance and development costs, your managers might say, 'okay, you've convinced us... let's give it a go, I'll give you a budget'
Other than figuring out which operating system and database to use and where (and how) your instance of Moodle is to be hosted, one of the first development activities you will have to do is make sure that your Moodle system is 'on brand', i.e. it's visual appearance should reflect the institution that you work for.
This is pretty much what I have to do. I have to try and make my 'vanilla' (unmodified) version of Moodle blend in with a set of existing web pages that have been built as a part of a research project I'm working on. Other development teams within my university have already done something similar with their production version of Moodle, but I need to tackle this problem myself.
I start with a couple of questions: what makes up a theme and how might you go about changing one or maybe even making a new one?
Resources galore
Before I can answer these questions I needed to find something to read, and it didn't take a lot of browsing to find a number of potentially useful resources.
The first page that I discovered was a link to over one hundred different themes thanks to the Database of Moodle Themes. Perhaps I shouldn't be so surprised given the number of Moodle installations that are out there in the world.
I soon discovered the Themes documentation pages and a number of other related links, including a set of themes related FAQs and dedicated discussion forum.
The Themes documentation link (for a Themes novice) seems to be the most useful. One of the sections says that themes can be delivered in zip files. You download them, unzip them and place the contents in the /moodle/theme directory, and then click on some admin tools to activate it. This sounds almost too easy!
Towards Code
Being someone who likes to view code I thought it might be useful to look at some of the magic that makes Moodle themes work. To do this, I chose a random theme from the themes database and unzipped a folder to my desktop. To begin to make sense of it properly, I felt that it might be a good idea to compare this random theme against one that already existed. This made me answer, 'which theme is used by default?'
To answer this question, I logged onto my local instance of Moodle (which was running on my local machine, localhost) as an administrator. After struggling to remember my username and password, I clicked on the Administration link, followed Appearance, Themes and then on the Theme Selector link (because I couldn't really make sense of the Theme Settings options).
I quite like the Theme Selector page. It presents all the different themes that have been installed. The current theme that is selected is highlighted by a black square. The one that was selected by default (in the case of my installation - I cannot remember whether I changed it) was named standardwhite.
I delve into the Moodle code area, take a copy of standardwhite and placed it alongside the one I have randomly downloaded and started poking around.
Looking at code
I noticed similarities and differences. The similarities are that some of the filenames are the same. I see two PHP files, styles and config, followed by two html files, header and footer. There seems to be a CSS file (Wikipedia) in both themes (but the downloaded theme contains a few more than the default theme). I also notice a graphics file called gradient in the default theme (which is a jpg), and a png graphics file in the other one. A big difference lies was that the theme I have downloaded contains a directory which seems to contain a bunch of graphic files.
Before deciding I'm terribly confused, I decide to do one more thing: open up both of the PHP files to see what they contain.
In a config script, I see assignments to a variable called $THEME. Different attributes appear to do different kinds of magic. Looking in the styles script, a comment tells me that 'there should be no need to modify this file'. It seems to do something that relates to the presentation of a CSS file. That is good enough for me!
I have a quick peek into the header and the footer html files. It looks like these are templates (of some kind) that are filled out using the contents of some PHP variables. Obviously the pages that the Moodle code creates have a pretty well defined structure, and presumably this structure is documented somewhere. This is perhaps something I might need to remember later.
Return to the documentation
At this point, I roughly (think) I know what a Theme comprises: some magic scripts which define some variables (and some other stuff), some header and footer scripts which look at bit like templates, a CSS file of some kind, perhaps a graphic (which could be used by the CSS file?) and maybe a bunch of graphics that replace those that are used in Moodle by default.
If this is my current understanding, can I now find the documentation easier to understand?
I soon uncover two further pages: Make your own Theme and Creating a Custom Theme (the first link seems to be easier to understand). A couple of clicks takes me to a documentation page called Theme config file which goes some way to explaining the variables that I have touched upon above.
The final comment in the Creating a Custom Theme page was instructive. Other than saying that you can't change everything, if you want to make your site look like an existing site, it might be a good idea to make use of a tool called Firebug which is a plug in for your Firefox browser.
With Firebug, you can browse to a web page of your choice and uncover what CSS definitions have been used to build its visual appearance. I've used Firebug before, and mentioning that it is a good tool is certainly a good piece of advice. The Moodle developers have also been kind enough to prepare a CSS FAQ which is certainly worth a look.
Although I could have tried to create a new theme from scratch, I'm in a lucky position since one of my colleagues has already created a customised theme for a custom instance of Moodle.
Towards testing things out
To test things out, I copy of my customised theme into my local 'themes' directory and hit refresh on my browser. I then select my newly installed theme and everything starts to go wrong. The action of selecting a theme seemed to have rendered my local copy of Moodle useless since only a tiny fraction of a HTML page is created (which I see by viewing the code the browser receives).
A problem seems to have been created since the version of Moodle that I am using and the structure of the theme that I have transferred are not completely compatible with each other. I need to go back to my default theme! But how do I do this? Where are the theme settings held?
My first guess is in the database. I open up a front end to the MySQL database that is running on my PC, using a tool called SqlYog. I eyeball the contents of the database to see if there's anything I can use. I discover a 'config' table, but this doesn't tell me much. I did, however, discover that there is a theme setting within individual courses as well as individual users.
I turn my attention towards the code by first looking at the code within the themes directory and I soon find myself fruitlessly searching through different libraries. Finding a simple answer may necessitate spending quite a bit of time.
To get things working again, you sometimes have to cheat. I renamed my theme to something totally different and refreshed my Moodle page. Moodle then had no choice but to return to its default setting (which was, again, 'standardwhite').
Incrementally merging
I have two themes: one theme that I want to use but doesn't work (because it has been modified for a customised version of Moodle), and another theme that does work which I don't want to use. When I'm faced with this situation, I try to get 'code to speak to me' by incrementally taking the one that works and making it look like the one that doesn't work. I find I can really understand stuff when things stop working!
I begin by looking at the files and then the contents of the files. The first thing that strikes me is that the header and footer files are quite different. There seems to be quite a bit more happening in the customised theme when compared to the standard theme. A step at a time I move files across and test, beginning with the favicon, then the config file, and finally the pix's. I discover that both themes require the use of a CSS file that is contained within the standard theme directory.
The effect of moving files around seems to produce, more or less, what I was after. The interactive 'side blocks' (particularly the show/hide buttons) are not presented as they should, but further searching reveals a magic variable, allowuserblockhiding that can be used to control this functionality.
Moodle version 2
A question to complete this post is: what is the situation regarding Moodle version 2.0? This is a development that I have heard about for some time, but I have not heard recent any announcements regaring its expected release. After a quick search, I reacquaint myself with something called the Moodle Roadmap.
This appears to state that there will be a beta release of V2 by the end of 2009, followed by some months of testing before a final release. Judging by the planning document, there appears to be quite a lot more coding to do (nearly four hundred days of development time to go, so we should expect some delays).
I appreciate that giving opinion is certainly a lot easier than giving code, so I hope that Moodlers who read this section will forgive me. I personally hope that the code for the next version is a lot cleaner. Since the developers are forced to move to PHP version 5, I hope they will choose to adopt its object-oriented features which can help developers to form clearer (less leaky) abstractions.
In a perfect world, developers should be able to look at a screenful of code and be able to describe, more or less, what that section of code does without having to look at other code (providing, of course, they more or less have an understanding of what the product does). From what I have seen so far in version 1.9, there is a long way to go to, but I'm certainly looking forward to learning how things have moved on in version 2.0.
Wrap-up
It's great that the developers of Moodle have designed it in such a way that it is 'themeable' (if there is such a word). In some respects, I was surprised to discover things were not as difficult as I had expected. Whilst, in some ways, going directly to the code and looking what is there may be a daunting challenge, it is one that I certainly recommend doing.
There's a whole lot more to the issue of Moodle themes. I haven't touched upon the structure of Moodle pages and how they relate to elements in stylesheets, for example. I'll leave this challenge for another day!