Themes for Elgg are both extremely easy to develop and incredibly powerful. Using themes you can completely change how an Elgg install looks and feels (and even behaves).
Since there has been a fair amount of discussion of themes on the groups, I thought it would be a good idea to write a brief post about it.
Themes use two key Elgg concepts – namely, the plugin architecture and the views system.
By far the easiest and flexible way to make a theme for Elgg is to build it as a plugin. This makes it easy to distribute (since they are self contained) and lets you turn the theme on and off from the admin panel (making the theming process far less invasive!)
What you must first do is create a new plugin directory under /mod (documented here). In a nutshell; create a directory in the name of your theme, a new start.php and a new manifest.xml.
Once you’ve done this you then can start modifying views. This can be done either by extension or by view overriding.
View extension
The first way is to add extra stuff to an existing view via the extend view function from within your start.php’s initialisation function.
For example, the following start.php will add mytheme/spotlight to the already existing site spotlight:
<?php
function mytheme_init()
{
extend_view('page_elements/spotlight','mytheme/spotlight');
}
register_elgg_event_handler('init','system','mytheme_init');
?>
View overriding
The next method is to override an existing theme, completely replacing it with the one provided by your plugin.
View files provided by plugins automatically take precedence over views from the core. So all we have to do to entirely replace the existing spotlight is to create a new spotlight.php in the appropriate hierarchy.
So, if the original view is stored in:
/elgg/views/default/page_elements/spotlight.php
We need to create the file:
/elgg/mod/mytheme/views/default/page_elements/spotlight.php
Now, when we go to the admin panel and activate our theme the spotlight will be replaced by whatever you put in that file. Simple eh?
You can of course do this with any view.
Using a combination of these methods means you can replace the entire look and feel of a site very quickly indeed, although I would suggest that you start slowly since many views do some quite complicated things.
I know I have seen this before while looking at code in plugins. Now it all makes sense!
A new tool to work with!
Thanks
Hi Marcus, Thanks for this article it is very helpful.
However there is a little detail that maybe could be confusing for some people (like me :D).
It is, how the “overwrite” view method works?
For example in the groups plugin you can see:
extend_view(“profile/icon”,”groups/icon”);
and if you check the code at profile/icon you can see some code that uses $vars[“overwrite”]. How defines if its the extension overwriting or not a view?
Thanks a lot.
@Diego
Overloading is done based on file location.
The core has a view hierarchy under /views/**
The plugin also has a view hierarchy under /mod/myplugin/views/**, which the engine then merges into /views/** in memory at runtime.
So, if in a plugin you have a file /mod/myplugin/views/default/whatever.php it will replace at runtime the file /views/default/whatever.php from core.
The engine doesn’t currently flag when this has happened, it just replaced.
Make sense?
Hi, how do I override images, icons from plugins and from parts of the core which are not referenced through the main CSS.
Thanks
Andreas
Nice post.
I have a question for you then – Without this knowledge, I have gone ahead with a dev version an elgg install and I’ve just set about tearing the default view apart in order to change colours etc.
This is horrid though and I need to keep things in their own seperate space.
The thing that confuses me is the number of plugins and modules that are installed (extra ones too), all seem to have their own seperate views to edit.
Even just editing the default view meant trawling through hundreds of folders and files in order to fine the right file to edit the pages appearance.
I’ve found this process very offputting.
If I am building my theme as a plugin, how do I test it thoroughly? How can see all the possible pages of the site and work out if my theme is working its magic in all the right places?
Will *all* my theme files be neatly within my plugins folder?
It would be nice if there were some official ‘themes’ (literally, just ‘design’ themes, not content themes necessarily available to view) and I think once there is one available, it should helpe people to understand.
OK. After some poking around, my question there needs to be more specific, sorry for the repost.
How would I, in my theme plugin, edit the layout of the ‘topbar’ in Elgg?
OR, as another example, the users profile page?
Tom I would think if you can override the view with you theme plugin if you replace view with the plugin you would like to extend it might work, maybe /mod/myplugin/mod/profile/views/default/icon/user/default/topbar.php but alas I am a newbie to elgg.