August 2008

Elgg developer Ben Werdmuller gave a very quick overview on how to create an Elgg 1.0 theme as a plugin. This approach has the advantage of leaving the core code intact. It is also handy because using the plugin system makes it easy to enable and disable themes within the Tool Administration interface.

The first step is to create a folder for your theme plugin:

/mynewtheme/

Within that folder create a blank text document entitled start.php. While not necessary, it is best to create a manifest.xml file in the same directory. This file gives a little information about your theme. Here is an example:

<?xml version=”1.0″ encoding=”UTF-8″?>
<plugin_manifest>
<field key=”author” value=”Steve O’Connor” />
<field key=”version” value=”1.0″ />
<field key=”description” value=”This is an alternative theme for elgg 1.0.” />
<field key=”website” value=”http://www.openedweb.com/” />
<field key=”copyright” value=”(C) Steve O’Connor 2008″ />
<field key=”licence” value=”GNU Public License version 2″ />
</plugin_manifest>

Now you should have:

/mynewtheme/
/mynewtheme/start.php
/mynewtheme/manifest.xml

The next step is to add a views directory and within that a default folder:

/mynewtheme/views/default/

You changes will all reside within that directory and any needed subdirectories.

If all you have done is taken the original css.php from elgg/views/default/ folder and hacked it as suggested in the previous post, you just pop your hacked css.php into your new theme:

/mynewtheme/views/default/css.php

Your changes can go beyond just altering the css.php. Let’s go back to the elgg core:

elgg/views/default/

Besides the css,php, there are other places one can edit. One such directory of particular interest is:

elgg/views/default/page_elements

It contains the following:

elgg_topbar.php
footer.php
header.php
owner_block.php
spotlight.php
title.php

Obvious places to edit include: elgg_topbar.php, footer.php, and header.php.

Once you are done editing any of these files, you need to place copies in your theme in a way that reflects the core view folder:

/mynewtheme/views/default/page_elements

Editing the elgg/views/default/pageshells/pageshells.php file would allow you to delete elements  (or add if you know how) to be displayed on the page. Again, save the edited file to your theme:

/mynewtheme/views/default/pageshells/pageshells.php

When you are done, you may have something like this:

/mynewtheme/
/mynewtheme/start.php
/mynewtheme/manifest.xml
/mynewtheme/views/default/css.php
/mynewtheme/views/default/page_elements/elgg_topbar.php
/mynewtheme/views/default/page_elements/header.php
/mynewtheme/views/default/page_elements/footer.php
/mynewtheme/views/default/pageshells/pageshells.php

Obviously, there are more modifications that can be made, but this gives everyone a starting point.

All that remains is to upload and activate the new theme. Use an ftp client to upload your new theme into the elgg/mods directory. Log in to Elgg as an administrator, Go to the Administration section and select Tools Administration. Click to enable your new theme. Now your changed files will override the core Elgg files.

That should get users started. You can do quite a bit by simply working with the css.php and packaging it as a plugin. I will continue to explore other options for customizing new themes.

Now that Elgg 1.0 is released, administrators may want to distinguish their site for all the other installations. As of this writing, there are no Elgg1.0 themes available nor has the Elgg Documentation Wiki yet been updated with instructions on theme development. There are some quick and easy ways to significantly change the appearance of your site.

The first thing you need to do is grab your ftp client and access yourelggdirectory/views/default/css.php and open it in your text editor. This is the heart of the appearance of your Elgg site. Now that you are looking at the code, it’s time to start hacking. Make sure you are working on a copy of css.php. If you mess things up, you can always upload your backup and restore the original theme.

Where do you start? First of all, the file is well commented by the elgg developers. There are also some cool tools can be a lot of help. One great free tool is a Firefox Plugin called Web Developer. Once you install Web Developer you will see a new tool bar on your browser.

Click to enlarge

Look for the CSS button, click it and select “View Style Information.”

Now, as you mouse over elements of the page, Web Developer will display the CSS style information for that element, giving you a pretty good idea where to alter the code to change its appearance.

Note the element is outlined in red above and the styles impacting it displayed directly below the tool bar. A quick peak at the code under those divisions should quickly reveal which needs to be edited.

Some elements such as the background are based upon graphics:

body {
	text-align:left;
	margin:0 auto;
	padding:0;
	background: #4690d6;
	font: 80%/1.4  "Lucida Grande", Verdana, sans-serif;
	color: #333333;
	background: url(<?php echo $vars['url']; ?>_graphics/page_back_linen.gif) repeat left 1px;
}

In that case you have the option of finding another graphic, or in some cases simply replacing it with a color.

Another handy option is to use your find/replace command to change colors en masse. This css file makes it easy because around line 70, you will find:

70 /* ***************************************
  71 	DEFAULTS
  72 *************************************** */
  73
  74 /* elgg open source		blue 			#4690d6 */
  75 /* elgg open source		dark blue 		#0054a7 */
  76 /* elgg open source		light yellow 	#FDFFC3 */

These are color elements that repeat many times in the file. By choosing a replacement color appropriate for each of the three is a quick and easy way to make changes to the theme.

Once you have made your changes, you can overwrite the css.php file to see the results, but a better approach is to use the override system. Simply save the file as css.css and upload it to yourelggdirectory/_css. This way, you still have the default available to fall back on if things did not work out as expected. Please refer to this post on installing themes as plugins.

You may want to change a few elements at a time then upload and view results. There are also some really handy css editors out that give real time feedback. CSSEdit for the Mac makes this process even easier! I’m sure there is something similar on other platforms.

Another thing that you may want to change is the text within Spotlight at the bottom of pages. One option is to write plugins to populate Spotlight, but that is beyond the scope of this post. The other way to edit it is to go to yourelggdirectory/views/default/spotlight/default.php. The commenting makes it clear where to edit.

While this in all probability does not represent the full procedure for developing an Elgg theme, this information will help change the look of your installation. You can do so with very little knowledge of CSS, but of course, the more you know, the easier it will be to make more significant changes.