Creating a PHP-Nuke theme gives your site its own special look, distinguishing it from other PHP-Nuke-created sites and offers an effective outlet for your creative talents. Creating a theme requires some knowledge of HTML, confidence in working with CSS and PHP, but most important is some imagination and creativity!

Unlike the tasks we have tackled in previous articles, where we have been working exclusively through a web browser to control and configure PHP-Nuke, working with themes is the start of a new era in your PHP-Nuke skills; editing the code files of PHP-Nuke itself. Fortunately, the design of PHP-Nuke means that our theme work won’t be tampering with the inner workings of PHP-Nuke. However, becoming confident in handling the mixture of HTML and PHP code that is a PHP-Nuke theme will prepare you for the more advanced work ahead, when we really get to grips with PHP-Nuke at the code level.

In this article, we will look at:

• Theme management
• Templates in themes
• Changing the page header
• Working with the stylesheet
• Changing blocks
• Changing the format of stories

What Does a Theme Control?

Despite the fact that we say ‘themes control the look and feel of your site’, a theme does not determine every aspect of the page output. PHP-Nuke is an incredibly versatile application, but it cannot produce every website imaginable.

Appearance

First of all, the appearance of the page can be controlled through the use of colors, fonts, font sizes, weights, and so on. This can either be done through the use of CSS styles or HTML. You can also add JavaScript for fancier effects, or even Flash animations, Java applets, or sounds—anything that you can add to a standard HTML page.

Graphical aspects of the page such as the site banner, background images, and so on, are under the care of the theme. There are also some modules that allow their standard graphical icons to be overridden with images from a theme.

Page Layout

Roughly speaking, a PHP-Nuke page consists of three parts; the top bit, the bit in the middle, and the bit at the bottom! The top bit—the header—usually contains a site logo and such things as a horizontal navigation bar for going directly to important parts of your site. The bottom bit—the footer—contains the copyright message.

In between the header and the footer, the output is usually divided into three columns. The left-hand column typically contains blocks, displayed one of top each other, the middle column contains the module output, and the right-hand column contains more blocks. The layout of these columns (their width for example) is controlled by the theme. You may have noticed that the right-hand column is generally only displayed on the homepage of a PHP-Nuke site; this too, is something that is controlled by the theme.

The appearance of the blocks is controlled by the theme; PHP-Nuke provides the title of the block and its content, and the theme will generally ‘frame’ these to produce the familiar block look.

The theme also determines how the description of stories appears on the homepage. In addition, the theme determines how the full text of the story, its extended text, is displayed.

We’ve talked about how the theme controls the ‘look’ of things. The theme also allows you to add other site-related data to your page; for example the name of the site can appear, and the site slogan, and you can even add such things as the user’s name with a friendly welcome message.

Theme Management

Basically, a theme is a folder that sits inside the themes folder in your PHP-Nuke installation. Different themes correspond to different folders in the themes folder, and adding or removing a theme is as straightforward as adding or removing the relevant folder from the themes folder.

By default, you will find around 14 themes in a standard PHP-Nuke installation. DeepBlue is the default theme.

Themes can be chosen in one of two ways:

• By the administrator: You can simply select the required theme from the General Site Info panel of the Site Preferences administration menu and save the changes. The theme selected by the administrator is the default theme for the site and will be seen by all users of the site, registered or unregistered.
• By the user: Users can override the default theme set by the administrator from the Themes option of the Your Account module. This sets a new, personal, theme that will be displayed to that user. Note that this isn’t a theme especially customized for that user; it is just one chosen from the list of standard themes installed on your site.

Unregistered visitors do not have an option to choose a theme; they have to become registered users.

Theme File Structure

Let’s start with the default theme, DeepBlue. If you open up the DeepBlue folder within the themes folder in the root of your PHP-Nuke installation, you will find three folders and two files. The three folders are:

• forums: This folder contains the theme for the Forums module. This is not strictly a requirement of a PHP-Nuke theme, and not every PHP-Nuke theme has a forums theme. The Forums module (otherwise known as phpBB) has its own theme ‘engine’. The purpose of including a theme for the forums is that you have consistency between the rest of your PHP-Nuke display and the phpBB display.
• images: This folder contains the image files used by your theme. These include the site logo, background images, and graphics for blocks among others. As mentioned earlier, within this folder can be other folders containing images to override the standard icons.
• style: This folder contains the CSS files for your theme. Usually, there is one CSS file in the style folder, style.css. Each theme will make use of its style.css file, and this is the file into which we will add our style definitions when the time comes.

Of the two files, index.html is simply there to prevent people browsing to your themes folder and seeing what it contains; visiting this page in a browser simply produces a blank page. It is a very simple security measure.

The themes.php file is a PHP code file, and is where all the action happens. This file must always exist within a theme folder. We will concentrate on this file later when we customize the theme.

In other themes you will find more files; we will look at these later.

Installing a New Theme

Installing and uninstalling themes comes down to adding or removing folders from the themes folder, and whenever a list of available themes is presented, either in the Site Preferences menu or the Your Accounts module, PHP-Nuke refreshes this list by getting the names of the folders in the themes folder.

You will find a huge range of themes on the Web. For example, there is a gallery of themes at:

http://nukecops.com/modules.php?set_albumName=packs&op=modload&name=Gallery& 
file=index&include=view_album.php

Many of these are themes written for older versions of PHP-Nuke, but most are still compatible with the newer releases.

There is also a live demonstration of some themes at:

http://www.portedmods.com/styles/

On this page you can select the new theme and see it applied immediately, before you download it.

Removing an Existing Theme

To remove a theme from your PHP-Nuke site you simply remove the corresponding folder from the themes folder, and it will no longer be available to PHP-Nuke.

However, you should be careful when removing themes—what if somebody is actually using that theme?

• If a user has that theme selected as their personal theme, and you remove that theme, then that user’s personal theme will revert to the default theme selected in Site Preferences.
• If you remove the site’s default theme, then you will break your site!

Deleting the site’s default theme will produce either a blank screen or messages like the following when you attempt to view your site.

Warning: head(themes/NonExistentTheme/theme.php)
[function.head]: failed to create stream:
No such file or directory in c:nukehtmlheader.php on line 31

The only people who can continue to use your site in this situation are those who have selected a personal theme for themselves—and only if that theme is still installed.

To correct such a faux pas, make a copy of one of the other themes in your themes folder (unless you happen to have a copy of the theme you just deleted elsewhere), and rename it to the name of the theme you just deleted.

In conclusion, removing themes should only be a problem if you somehow manage to remove your site’s default theme. For users who have selected the theme you just removed, their theme will revert to the default theme and life goes on for them.

A final caveat about the names of theme folders; do not use spaces in the names of the folders in the themes folder—this can lead to strange behavior when the list of themes is displayed in the drop-down menus for users to select from.

From an Existing Theme to a New Theme

We’ll create a new theme for the Dinosaur Portal by making changes to an existing theme. This will not only make you feel like the theme master, but it will also serve to illustrate the nature of the theme-customization problem. We’ll be making changes all over the place—adding and replacing things in HTML and PHP files—but it will be worth it. Another thing to bear in mind is that we’re creating a completely different looking site without making any changes to the inner parts of PHP-Nuke. At this point, all we are changing is the theme definition.

The theme for the Dinosaur Portal will have a warm, tropical feel to it to evoke the atmosphere of a steaming, tropical, prehistoric jungle, and will use lots of orange color on the page.

First of all, we need a theme on which to conduct our experiments. We’ll work on the 3D-Fantasy theme.

Starting Off

The first thing we will do is to create a new theme folder, which will be a copy of the 3D-Fantasy theme.

Open up the themes folder in your file explorer, and create a copy of the 3D-Fantasy folder. Rename this copy as TheDinosaurPortal.

Now log into your site as testuser, and from the Your Account module, select TheDinosaurPortal as the theme. Your site will immediately switch to this theme, but it will look exactly like 3D-Fantasy, because, at the moment, it is!

You will also need some images from the code download for this article; you will find them in the SiteImages folder of this article’s code.

Replacing Traces of the Old Theme

The theme that we are about to work on has many occurrences of 3D-Fantasy in a number of files, such as references to images. We will have to remove these first of all, or else our new theme will be looking in the wrong folder for images and other resources.

Open each of the files below in your text editor, and replace every occurrence of 3D-Fantasy with TheDinosaurPortal in a text editor, we’ll use Wordpad. “You can use the replace functionality of your editor to do this. For example, in Wordpad, select Edit | Replace; enter the text to be replaced, and then click on Replace All to replace all the occurrences in the open file. After making all the changes, save each file:

• blocks.html
• footer.html
• header.html
• story_home.html
• story_page.html
• theme.php
• tables.php

Templates and PHP Files

We’ve just encountered two types of file in the theme folder—PHP code files (theme.php and tables.php) and HTML files (blocks.html, footer.html, and so on). Before we go any further, we need to have a quick discussion of what roles these types of file play in the theme construction.

PHP Files

The PHP files do the main work of the theme. These files contain the definitions of some functions that handle the display of the page header and how an individual block or article is formatted, among other tasks. These functions are called from other parts of PHP-Nuke when required. We’ll talk about them when they are required later in the article. Part of our customization work will be to make some changes to these functions and have them act in a different way when called.

Historically, the code for a PHP-Nuke theme consisted of a single PHP file, theme.php. One major drawback of this was the difficulty you would have in editing this file in the ‘design’ view of an HTML editor. Instead of seeing the HTML that you wished to edit, you probably wouldn’t see anything in the ‘design’ view of most HTML editors, since the HTML was inextricably intertwined with the PHP code. This made creating a new theme, or even editing an existing theme, not something for the faint-hearted—you had to be confident with your PHP coding to make sure you were changing the right places, and in the right way.

The theme.php file consists of a number of functions that are called from other parts of PHP-Nuke when required. These functions are how the theme does its work.

One of the neat appearances in recent versions of PHP-Nuke is the use of a ‘mini-templating’ engine for themes. Not all themes make use of this method (DeepBlue is one theme that doesn’t), and that is one of the reasons we are working with 3D-Fantasy as our base theme, since it does follow the ‘templating’ model.

Templates

The HTML files that we modified above are the theme templates. They consist of HTML, without any PHP code. Each template is responsible for a particular part of the page, and is called into action by the functions of the theme when required.

One advantage of using these templates is that they can be easily edited in visual HTML editors, such as Macromedia’s Dreamweaver, without any PHP code to interfere with the page design.

Another advantage of using these templates is to separate logic from presentation. The idea of a template is that it should determine how something is displayed (its presentation). The template makes use of some data supplied to it, but acquiring and choosing this data (the logic) is not done in the template. The template is processed or evaluated by the ‘template engine’, and output is generated. The template engine in this case is the theme.php file.

To see how the template and PHP-Nuke ‘communicate’, let’s look at an extract from the header.html file in the 3D-Fantasy folder:

<a href="index.php">
   <img src="themes/3D-Fantasy/images/logo.gif" border="0"
        alt="Welcome to $sitename" align="left">
</a>

The $sitename text (shown highlighted) is an example of what we’ll call a placeholder. There is a correspondence between these placeholders and PHP variables that have the same name as the placeholder text. Themes that make use of this templating process more or less replace any text beginning with $ in the template by the value of the corresponding PHP variable.

This means that you can make use of variables from PHP-Nuke itself in your themes; these could be the name of your site ($sitename), your site slogan, or even information about the user. In fact, you can add your own PHP code to create a new variable, which you can then display from within one of the templates.

To complete the discussion, we will look at how the templates are processed in PHP-Nuke. The code below is a snippet from one of the themeheader() function in the theme.php file. This particular snippet is taken from the 3D-Fantasy theme.

function themeheader()
{
    global $user, $banners, $sitename, $slogan, $cookie, $prefix,
           $anonymous, $db;
... code continues ....

$tmpl_file = "themes/3D-Fantasy/header.html";
$thefile = implode("", file($tmpl_file));
$thefile = addslashes($thefile);
$thefile = "$r_file="".$thefile."";";
eval($thefile);
print $r_file;
... code continues ....

The processing starts with the line where the $tmpl_file variable is defined. This variable is set to the file name of the template to be processed, in this case header.html. The next line grabs the content of the file as a string. Let’s suppose the header.html file contained the text You’re welcomed to $sitename, thanks for coming!. Then, continuing in the code above, the $thefile variable would eventually hold this:

$r_file = " You're welcomed to $sitename, thanks for coming!";

This looks very much like a PHP statement, and that is exactly what PHP-Nuke is attempting to create. The eval() function executes the statement; it defines the variable $r_file as above. This is equivalent to putting this line straight into the code:

$r_file = " You're welcomed to $sitename, thanks for coming!";

If this line were in the PHP code, the value of the $sitename variable will be inserted into the string, and this is exactly how the placeholders in the templates are replaced with the values of the corresponding PHP variables.

This means that the placeholders in templates can only use variables accessible at the point in the code where the template is processed with the eval() function. This means any parameters passed to the function at the time—global variables that have been announced with the global statement or any variables local to the function that have been defined before the line with the eval() function. This does mean that you will have to study the function processing the template to see what variables are available. In the examples in this article we’ll look at the most relevant variables.

The templates do not allow for any form of ‘computation’ within them; you cannot use loops or call PHP functions. You do your computations ‘outside’ the template in the theme.php file, and the results are ‘pulled’ into the template and displayed from there.

Now that we’re familiar with what we’re going to be working with, let’s get started.

Changing the Page Header

The first port of call will be creating a new version of the page header. We will make these customizations:

• Changing the site logo graphic
• Changing the layout of the page header
• Adding a welcome message to the user, and displaying the user’s avatar
• Adding a drop-down list of topics to the header
• Creating a navigation bar

Time For Action—Changing the Site Logo Graphic

1. Grab the <>ilogo.gif file from the SiteImages folder in the code download.
2. Copy it to the themes/TheDinosaurPortal/images folder, overwriting the existing logo.gif file.
3. Refresh the page in your browser. The logo will have changed!

What Just Happened?

The logo.gif file in the images folder is the site logo. We replaced it with a new banner, and immediately the change came into effect.

Time For Action—Changing the Site Header Layout

1. In the theme folder is a file called header.html. Open up this file in a text editor, we’ll use Wordpad.
2. Replace all the code in this file with the following:

<!-- Time For Action—Changing the Site Header Layout -->
<table border="0" cellspacing="0" cellpadding="6" width="100%"
       bgcolor="#FFCC33">
 <tr valign="middle">
  <td width="60%" align="right" rowspan="2">
  <a href="index.php"><img src="themes/$GLOBALS[ThemeSel]/images/logo.gif"
                           border="1" alt="Welcome to $sitename">
  </a></td>
  <td width="40%" colspan="2">
    <p align="center"><b>WELCOME TO $sitename!</b></td>
 </tr>
 <tr>
   <td width="20%">GAP</td>
   <td width="20%">GAP</td>
 </tr>
</table>
<!-- End of Time for Action -->
$public_msg<br>
<table cellpadding="0" cellspacing="0" width="99%" border="0"
       align="center" bgcolor="#ffffff">
<tr><td bgcolor="#ffffff" valign="top">

3. Save the header.html file.
4. Refresh your browser. The site header now looks like this:

What Just Happened?

The header.html file is the template responsible for formatting the site header. Changing this file will change the format of your site header.

We simply created a table that displays the site logo in the left-hand column, a welcome message in the right-hand column, and under that, two GAPs that we will add more to in a moment. We set the background color of the table to an orange color (#FFCC33). We used the $sitename placeholder to display the name of the site from the template.

Note that everything after the line:

<!-- End of Time for Action -->

in our new header.html file is from the original file. (The characters here denote an HTML comment that is not displayed in the browser). This is because the end of the header.html file starts a new table that will continue in other templates. If we had removed these lines, the page output would have been broken.

There was another interesting thing we used in the template, the $GLOBALS[ThemeSel] placeholder:

<a href="index.php"><img src="themes/$GLOBALS[ThemeSel]/images/logo.gif"

ThemeSel is a global variable that holds the name of the current theme—it’s either the default site theme or the user’s chosen theme. Although it’s a global variable, using just $ThemeSel in the template would give a blank, this is because it has not been declared as global by the function in PHP-Nuke that consumes the header.html template. However, all the global variables can be accessed through the $GLOBALS array, and using $GLOBALS[ThemeSel] accesses this particular global variable. Note that this syntax is different from the way you may usually access elements of the $GLOBALS array in PHP. You might use $GLOBALS[‘ThemeSel’] or $GLOBALS[“ThemeSel”]. Neither of these work in the template so we have to use the form without the ‘ or “.

Time For Action—Fixing and Adding the Topics List

Next we’ll add the list of topics as a drop-down box to the page header. The visitor will be able to select one of the topics from the box, and then the list of stories from that topic will be displayed to them through the News module. Also, the current topic will be selected in the drop-down box to avoid confusion.

This task involves fixing some bugs in the current version of the 3D-Fantasy theme.

1. First of all, open the theme.php file and find the following line in the themeheader() function definition:

$topics_list = "<select name="topic" onChange='submit()'>n";

2. Replace this line with these two lines:

global $new_topic;
$topics_list = "<select name="new_topic" onChange='submit()'>n";

3. If you move a few lines down in the themeheader() function, you will find this line:

if ($topicid==$topic) { $sel = "selected "; }

4. Replace $topic with $new_topic in this line to get:

if ($topicid==$new_topic) { $sel = "selected "; }

5. Save the theme.php file.
6. Open the header.html file in your text editor, and where the second GAP is, make the modifications as shown below:

<td width="20%">GAP</td>
  <td width="20%"><form action="modules.php?name=News&new_topic"   method="post">
  Select a Topic:<br>$topics_list</select></form></td>
</tr>
</table>
<!-- End of Time for Action -->

7. Save the header.html file.
8. Refresh your browser. You will see the new drop-down box in your page header:

What just Happened?

The themeheader() function is the function in theme.php responsible for processing the header.html template, and outputting the page header.

The $topics_list variable has already been created for us in the themeheader() function, and can be used from the header.html template. It is a string of HTML that defines an HTML select drop-down list consisting of the topic titles.

However, the first few steps require us to make a change to the $topics_list variable, correcting the name of the select element and also using the correct variable to ensure the current topic (if any) is selected in the drop-down box. The select element needs to have the name of new_topic, so that the News module is able to identify which topic we’re after.

This is all done with the changes to the theme.php file. First, we add the global statement to access the $new_topic variable, before correcting the name of the select element:

global $new_topic;
$topics_list = "<select name="new_topic" onChange='submit()'>n";

The next change we made is to make sure we are looking for the $new_topic variable, not the $topic variable, which isn’t even defined:

if ($topicid==$new_topic) { $sel = "selected "; }

Now the $topics_list variable is corrected, all we have to do is add a placeholder for this variable to the header.html template, and some more HTML around it. We added the placeholder for $topics_list to display the drop-down list, and a message to go with it encouraging the reader to select a topic into one of the GAP table cells we created in the new-look header.

The list of topics will be contained in a form tag, and when the user selects a topic, the form will be posted back to the server to the News module, and the stories in the selected topic will be displayed. (The extra HTML that handles submitting the form is contained with the $topics_list variable.)

<form action="modules.php?name=News" method="post">
Select a Topic:<br>$topics_list

All that remains now is to close the select tag—the tag was opened in the $topics_list variable but not closed—and then close the form tag:

</select></form>

When the page is displayed, this is the HTML that PHP-Nuke produces for the topics drop-down list:

<form action="modules.php?name=News&new_topic" method="post">
Select a Topic:<br><select name="topic" onChange='submit()'>
<option value="">All Topics</option>
<option value="1">The Dinosaur Portal</option>
<option value="2">Dinosuar Hunting</option>
</select></form>