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!