How to Make an Exponent CMS Theme

A guide on how to make your own themes for the Exponent Content Management System

Exponent CMS is an open source content management system, available free to anyone at Sourceforge. As I noted in my review of Exponent CMS, at this moment, I believe that Exponent CMS is the best CMS out there (at least, for what I'm doing). If you want to allow anybody to add content, edit content, add pages, etc, then Exponent is by far the simplist.

Unfortunatly, at this moment, Exponent does not have much documentation available. My first theme was done by hacking an exhisting theme, and trying to figure out what was going on. Right now, there is an incomplete theme guide at the Exponent Support Wiki, which I highly recommend reading. But this guide is more technical (it is meant to be documentation), and not as practical. My goal here is to hopefully explain the process of theming in Exponent well and completely enough that you can start making your own themes without any problems.

Create your Template

Before you start anything, create your design like you are creating any normal HTML page. You do not have to worry about Exponent. To turn your template into a working Exponent theme, you only need to add a few lines of code. So create your template, and save it and all of its files somewhere on your hardrive. We'll get back to those in a second.

Theme Basics

The goal of Exponent and other content management systems is to seperate design from layout. It should be possible to change the layout and design of an entire site without having to change any of the content. There are basically three ways to customize the appearance of content in Exponent:

  • /themes/yourtheme/index.php: This file is your layout file. This is where you tell Exponent to place modules, and where you put the html for your page.
  • /themes/yourtheme/style.css: This is the CSS file. Here you can also define the layout of your site (if you use CSS for layouts), and also style the text in Exponent's modules.
  • themes/yourtheme/modules/modulename/views/_____.tpl: You can also define how exponent displays certain modules. For example, you can control how the text module looks, or if the login module will have a border. The Exponent installation has these module views in /modules/, in order to seperate themes from each other, you can copy these modules into your template directory, and then edit the view files without changing it for the rest of the site.

Getting Started

Setting up the theme

You have to set up the theme so that Exponent will recognize it. What I recommend is to find an exhisting theme, and make a copy of that directory. That way, you start with a working theme, and you can just delete the unused files at the end.

So first, put the copy under exponentinstallationroot/themes/. Rename the folder to "_________theme". There are a few restrictions:

  • It must be all lower case
  • Only alphanumeric characters
  • Must end in "theme"

So now along with "corporatetheme" and "defaulttheme" in the theme/ directory, you should see "____theme".

Now, open the class.php file inside of your theme folder. This tells exponent basic information about your theme. You will need to change 4 things. I have included the file, and highlighted in red what you need to change. (comments taken from documentation)

<?php // Start PHP code
// Theme class definition
// This MUST be what you named your theme folder. So change,
// INTERNALNAME to "_______theme"
class INTERNALNAME {

// A descriptive name for the theme. This will be seen
// by people choosing themes in the site configuration.
// It will also be seen by anyone managing themes
// from the administration control panel.
function name() {
return "Theme Name";
}

// A short description of the theme.
function description() {
return "This is a basic description of your theme";
}

// Your name
function author() {
return "Your name";
}
}
?>

Now copy all of your files over to the theme directory. There might be an images directory, but you don't have to put your images in there. If you aren't going to use the directory, delete it. We only copied another theme directory to save time.

index.php

Now, rename the file your template is in to index.php, and open the file in a text editor. First, add this line to the top of your file.

<?php
if (!defined('PATHOS')) exit('');
?>

This is simply a security measure.

Now, you need to setup links to your additional files (such as your css files or your images). Because this theme is stored in yourdomain.com/themes/, relative URL's will not work. So you need to include this line of code, which just prints out the base path to your theme directory:

<?php echo THEME_RELATIVE;?>

So for example,

Replace:
<link rel="stylesheet" title="default" href="style.css" />
With:
<link rel="stylesheet" title="default" href="<?php echo THEME_RELATIVE;?>style.css" />

Last, you need to allow Exponent Javascript to run. So,

Replace:

<body>
With:
<body onLoad="pathosJSinitialize();">

Adding content

You need to add this code where the main content of your page is going to go:

<?php pathos_theme_main(); ?>

Adding Modules

Modules are what Exponent uses to add things into your theme. You can add theme into index.php ONLY if you want them displayed on every page. Otherwise, you can add them with Expoonent.

This is how you add a module:

<?php
pathos_theme_showModule("modulename","Viewname");
?>

You can use FTP and look in the modules directory to see available modules.

Here is a list of common modules you might want to add:

Container Module: For a left or right column. Below, "Narrow" is the name of the view, and "@sidebar" is your descriptive name of the container.

<?php pathos_theme_showSectionalModule("containermodule","Narrow","","@sidebar")?>
Text Module: Possibly for a copyright footer
<?php pathos_theme_showModule("textmodule","Footer","","footer"); ?>
Login Module: To login have a login module on each page (or just use yourdomain.com/login.php)
<?php pathos_theme_showModule("loginmodule","Default"); ?>
Preview Module: For admins to preview the page, only use if you want it on every page.
<?php pathos_theme_showModule("previewmodule","Default"); ?>




You can also customize the view of modules in you theme. For example, you can change how the login module is displayed, or how the navigation module is displayed.

If you want to customize the view of the module, you need to make a subfolder with the name of the module in the root directory of your theme (along with index.php).

So for example, we will be making a new view for the navigation module. Add this code to your index.php

<?php
pathos_theme_showModule("navigationmodule","Custom");
?>

So you will have a subfolder named "navigationmodule". Now make a subfolder under "navigationmodule", and name it "views". Under that folder make a file called "Custom.tpl". Notice how the first part of your php code links to the folder name, and the other links to the name of you .tpl file under another subfolder called views.

All module views are written in Smarty. You can learn about it here

I highly recommend editing exhisting themes, such as the portal theme, instead of making new themes. It will help you learn.

Uploading

You can either upload your themes directory through FTP to the /themes directory, or install it through Exponent. To install it through exponent, compress your theme directory to a tar.gz file, then use the upload extension tool in the Exponent Admin panel.

Thanks for reading. If you have any comments or suggestions, please comment below. I respond to every comment, so comment away!

Rate this Tutorial

Rate this Tutorial:

Current Rating:

3 out of 53.19/ 5.00 with 16 votes.

Current Comments

11 comments so far (post your own)

Hi...This tutorial is great, but I was wondering if you could replace the yellow font with something that is easier to read on a white background. Thanks so much for making this tutorial. I hope more people follow suit.

Posted by shana on Sunday, 02.12.06 @ 11:05am | #838

Great Tutorial - but i have to change to a different template to edit my site. Any ideas?

Posted by Rob Daglish (http://www.robdaglish.co.uk/)on Monday, 07.3.06 @ 03:02am | #2235

I tried this the first time and it worked. Then I tried it on a new site I installed and it wont work now. I followed all the steps, but when I am done and I go to the "Manage Themes" page, it falls over. The page shows nothing. Not even the other installed themes. Even the "configure Site" page bombs out. I cant figure out why this happens. I tried using the extension upload page to upload the theme, but all this does is dump my theme in the root folder and not the theme directory. Im lost. I would appreciate some advice please.

Posted by Jalaloedien on Thursday, 07.6.06 @ 05:21am | #2244

Jalaloedien, make sure you change all the lines

if (class_exists('mytheme')) return/;

class mytheme {
function name() { return "my theme"/; }
function author() { return "me"/; }
function description() { return "A simple page theme."/; }
}

I had the same thing just happen to me. The theme manager just showed up empty. It was because I forgot to say "class [theme name] {". Instead, I changed everything else, and accidently left that saying "class portaltheme {", and well, it didn't display anything because I had two portal themes.

Posted by Tim on Wednesday, 07.12.06 @ 09:32am | #2255

I had the same problem... Found that it was my theme file just as discripbed above!

Once I got that straightened out, twas smooth sailing!

Winslow

Posted by Winslow (nada.com)on Wednesday, 08.30.06 @ 12:22pm | #2586

I also had a monkey. Thats was fun...

Winslow

Posted by Winslow (nada.com)on Tuesday, 10.31.06 @ 11:42am | #2645

i was wondering how you get the actual themes to become the current theme. I have a few I have made and compressed in ZIP format, and I want to use one, but there is no activate button or link anywhere... what am I doing wrong?

Posted by matt (xilambda.5gbfree.com/exponent/)on Friday, 01.12.07 @ 12:33pm | #2714

Hi, Thanks for the article, really useful. I am viewing this site with IE6 and the tabs at the top are flickering - try putting

document.execCommand("BackgroundImageCache",false,true)

In script tags at the head of your doc (best wrapped in a try catch loop) - this will prevent that and make it work more smoothly :)

Posted by Rob (http://www.cypherdesign.net)on Wednesday, 02.28.07 @ 04:08pm | #2777

it has uploaded successfully
but not appeared onto the theme managment !!

Posted by mokhtar on Monday, 03.12.07 @ 07:40am | #2786

Is there any way to use different themes on different pages? Thanks.

Posted by dan (www.ruddicklandscapes.co.uk/index.php)on Tuesday, 04.10.07 @ 03:21am | #2837

I follow every thing.. the upload was successfull. BUT i can't find the theme name I edit... What did i do wrong? can anyone help me.. TY

Posted by emc on Tuesday, 05.29.07 @ 10:11pm | #2909

Leave your comment:

Learn how to add this comment form to your site with our comment form tutorial!

Name:

Email:

URL:

Comments:


 
Guess the letters and numbers
(passphrase riddle)
--
small 'Q' +3 letters
and not a
"M",
but
2 chars before Y
and
(((??? * 1) - 3) - 8) = -5;
"8"
and not a
"M",
but
'Y' +1 letters
followed by
2 chars before small L
and
→ retype that here
Enter the correct letters and numbers from the image into the text box. This small test serves as access restriction against malicious bots. Simply reload the page if this graphic is too hard to read.
 

Note: Emails will not be visible or used in any way, and are not required. Please keep comments relevant. Any content deemed inappropriate or offensive may be edited and/or deleted.

No HTML code is allowed. Line breaks will be converted automatically. URLs will be auto-linked. Please use BBCode to format your text.