XOOPS Theme Tutorial
by mC

Changes
01/10/02
- Changed from fixed width to relative widths
- Corrected an error in the PHP where ' was interchanged with "
- Removed width parameter in OpenTable()
30/09/02
- Wrote tutorial
- Public release

Special Thanks
T_Tellus - for his tutorial that allowed me to create my very first theme

Introduction
Hello everyone! This is my first tutorial for XOOPS so please be patient as it might have a few errors in it. Please let me know and I'll correct the error. I hope you'll find this useful and informative.

Making a theme for XOOPS seems like such a difficult task, but honestly it's quite easy if you know what you're doing. This tutorial will run you through 10 easy steps to create a new theme from scratch without having to know any PHP whatsoever. I have also included a sample theme that I made while writing this tutorial. Feel free to use it as a reference if you get lost.

The only thing that this tutorial will assume is the following:
    - you know basic HTML
    - have a WYSIWYG HTML Editor (and know how to use it)
    - have a text editor
    - English is the default language for your xoops

And now for the tutorial...

Step 1 - Creating required directories
We must create a directory in which to store our design, php, image, style, and language files. Depending on your OS, create a directory for your theme. In our case, I will use "anime". Within this directory, create an "images", a "style" and a "language" folder. Below is the directory structure that we should have so far:

+ anime
    + images
    + language
    + style

Step 2 - Creating the design layout
Ok so now, we can create our very own design. Fire up your HTML editor and let the creative juices flow. There are a few things that we must keep in mind when creating our design:

A block is the table that is used as a place holder for the title, and contents.

Use a 3 column layout (a left, centre and right column)
Have a place to display banners (if needed)
Have a place to display the footer (if needed)
Use a relative width for the left, right and centre columns (20%, 60%, etc)
Create 1 sample block for both left and right columns (include the HTML code that separates the blocks together ie. <br>, <table><tr><td> </td></tr></table>, etc.)
Create 2 sample blocks for the centre column (one for centre blocks, and one for posts. also don't forget to include the HTML code that separates the block/posts)
Do not format any fonts (we will do this later using the CSS file)
Insert "<link rel="stylesheet" type="text/css" href="style/style.css">" before the </head> tag
Align the fonts, table, images as needed ie. center, right, left, top, etc.

Use keywords to identify the location of certain elements:

Element name	What it does
{URL}	Inserts the site's URL
{BANNER}	Placeholder for the banners
{TITLE}	Shows the title for the specific block
{CONTENT}	Shows the content for the specific block
{POSTEDBY}	Shows "Posted by" depending on language
{AUTHOR}	Shows the author of the article
{ON}	Shows "on" depending on language
{DATE}	Shows the date the article was published
{COUNTER}	Shows the number of times the article has been read
{READS}	Shows "reads" depending on language
{IMG}	Shows the topic image for the article
{TEXT}	Shows the text for the article
{ADMINLINK}	Shows the Admin links for the article (edit, delete, etc.)
{MORELINK}	Shows the "Read More" and "Comments?" links
{FOOTER}	Placeholder for the footer

Ok so now that we've finished our design. We need to save our work in its proper location. Below is the directories in which the files belong:

Save the HTML file as "html.htm" and the images in the "images" folder

+ anime
    - html.htm
    + images
        - arrow.gif
        - logo.jpg
    + language
    + style

Step 3 - Copying required files
Once you've finished creating your theme, we then copy the 4 required files "theme.php", "themenews.php", "style.css" and "lang-english.php" into their proper locations. Copy the 4 files into their directories as shown below:

+ anime
    - html.htm
    - theme.php
    - themenews.php
    + images
        - arrow.gif
        - logo.jpg
    + language
        - lang-english.php
    + style
        - style.css

Okay, so now we have all the files we need to start editing the files for our theme.

Step 4 - Editing html.htm
Fire up your HTML editor again and open up html.htm. We will now add the comments needed to separate the sections we need for the PHP files later on.

Comment name Place to be inserted into

 Before the HTML code for left block begins

 After the HTML code for the left block, include the separating code mentioned in Step 2

 Before the HTML code for centre block begins

 After the HTML code for the centre block, include the separating code mentioned in Step 2

 Before the HTML code for post block begins

 After the HTML code for the post block, include the separating code mentioned in Step 2

 Before the HTML code for right block begins

 After the HTML code for the right block, include the separating code mentioned in Step 2

Once that's finished, save the file and let's move on. We will replace the tags that we placed earlier in Step 2 with the proper PHP code. Replace the tags as below:

You must do the replacing in source code mode and not WYSIWYG mode.

Element name Replacement PHP code

{URL} <?php echo XOOPS_URL;?>

{BANNER} <?php if ($xoopsConfig["banners"]) { showbanner(); }?>

{TITLE} <?php echo $title;?>

{CONTENT} <?php echo $content;?>

{POSTEDBY} <?php echo _TH_POSTEDBY;?>

{AUTHOR} <?php echo $poster;?>

{ON} <?php echo _TH_ON;?>

{DATE} <?php echo $time;?>

{COUNTER} <?php echo $counter;?>

{READS} <?php echo _TH_READS;?>

{IMG} <?php echo $timglink;?>

{TEXT} <?php echo $thetext;?>

{ADMINLINK} <?php echo $adminlink;?>

{MORELINK} <?php echo $morelink;?>

{FOOTER} <?php echo $footer;?>

Once you've finished replacing all the tags, save the file as php.htm in the same directory as html.htm, as shown below:

+ anime
    - html.htm
    - php.htm
    - theme.php
    - themenews.php
    + images
        - arrow.gif
        - logo.jpg
    + language
        - lang-english.php
    + style
        - style.css

Step 5 - Editing style.css
So now we have the layout all done, we'll start editing the colours of the theme. Open up "style.css" in either a text editor or your HTML editor.

You should see the following:

/* base styles */
body { background: #FFFFFF; color: #000000; font: 10pt Verdana }
td { font-family: Verdana; font-size: 10pt }
input { font: 10pt Verdana; border-color: #000000; border-width: 1px; background-color : transparent } /* leave the background colour as transparent due to option buttons */
textarea { font: 10pt Verdana; border-color: #000000; border-width: 1px; background-color : #FFFFFF }
select { font: 10pt Verdana; border-color: #000000; border-width: 1px; background-color : #FFFFFF }

/* links style */
a:link { color: #000000; text-decoration: none }
a:visited { color: #000000; text-decoration: none }
a:active { color: #000000; text-decoration: none }
a:hover { color: #000000; text-decoration: underline }

/* custom style */

/* required styles */
img { border:0px none } /* do not change */
.ahem { display:none } /* do not change */
.bg1{ background-color:#FFFFFF } /* module main */
.bg2 { background-color:#000000 } /* border colour tables (poll, forum, etc) */
.bg3 { background-color:#EEEEEE } /* module title/sub-title/misc */
.bg4 { background-color:#FFFFFF } /* should be the same as bg1 */
.fg1 { color:#000000 } /* text colour */
.fg2 { color:#000000 } /* text colour */

Everything is pretty much self-explanatory except for a few small details:

You can create your own custom styles, just be sure to add them back in both the html.htm, and php.htm
The bg1-4 are background colours used by modules
The fg1-2 are text colours used by modules as well

So just experiment with the colours and see which one comes out best for your theme. Have index.htm open so you can just refresh to see the changes. Don't forget to save ;)

Step 6 - Editing lang-english.php
Open up lang-english.php, and you should see the following:

<?php
define("_TH_POSTEDBY","Posted by");
define("_TH_ON","on");
define("_TH_READS","reads");
?>

These are the text that are used to replace:

<?php echo _TH_POSTEDBY;?>
<?php echo _TH_ON;?>
<?php echo _TH_READS;?>

Change the text as you see appropriate, or even maybe add your own. Just don't forget to add them back in php.htm

Step 7 - Editing themenews.php
Now we have all the editing done, we just need to proceed with the inserting of the HTML into the PHP files. Open up both php.htm and index.htm in your HTML editor and themenews.php in a text editor. Below you'll see something similar in themenews.php:

On the part where it says HTML CODE, we will replace that with the part within  and

You should have something similar to below:

<?php
/************************************************************/
/* Theme Name: THEMENAME */
/* By AUTHOR */
/* Copyright (c) YEAR AUTHOR */
/* Last Updated: MONTH/DATE/YEAR */
/************************************************************/

/************************************************************/
/* Function themenews() */
/* */
/* This function formats the stories on the homepage */
/************************************************************/

function themenews($poster, $time, $title, $counter, $thetext, $timglink, $adminlink, $morelink="") {
global $xoopsTheme;
?>
<table style="BORDER-COLLAPSE: collapse" bordercolor="#111111" cellspacing="0" cellpadding="0" width="99%" border="0">
<tr>
<td width="100%">
<table style="BORDER-COLLAPSE: collapse" bordercolor="#808080" cellspacing="0" cellpadding="0" width="100%" border="1" align="center">
<tr>
<td width="100%" bgcolor="#666666"><?php echo $title;?></td>
</tr>
<tr>
<td width="100%" bgcolor="#444444"> <img height="7" src="images/arrow.gif" width="7" border="0"><?php echo _TH_POSTEDBY;?> <?php echo $poster;?> <?php echo _TH_ON;?> <?php echo $time;?> (<?php echo $counter;?> <?php echo _TH_READS;?>)<br>
<br>
<?php echo $timglink;?> <?php echo $thetext;?><br>
 </td>
</tr>
<tr>
<td width="100%" bgcolor="#444444" align="right"><?php echo $adminlink;?> <?php echo $morelink;?></td>
</tr>
</table>
</td>
</tr>
</table><br>
<?php
}
?>

Don't forget to change the theme information at the top of the file.

Now we save themenews.php, and close it as that's all that needs to be done for themenews.php.

Step 8 - Editing theme.php
Ok, now open up theme.php and you it should resemble something similar to below:

We will dissect the contents part by part, and show you what HTML code needs to be added for each section.

<?php
/************************************************************/
/* Theme Name: THEMENAME */
/* By AUTHOR */
/* Copyright (c) YEAR AUTHOR */
/* Last Updated: MONTH/DATE/YEAR */
/************************************************************/

// Change to the foldername of your theme
$xoopsTheme['thename'] = "THEMENAME";

We will change THEMENAME to the name of our theme, "anime" in our case.

/************************************************************/
/* Function themesidebox() */
/* */
/* Controls the look of your left blocks. */
/************************************************************/

function themesidebox($title, $content) {
global $xoopsTheme;
?>
HTML CODE
<?php
}

Replace HTML CODE with the HTML code between  and  in php.htm

/************************************************************/
/* Function themesidebox_right() */
/* */
/* Controls the look of your right blocks. */
/************************************************************/

function themesidebox_right($title, $content) {
global $xoopsTheme;
?>
HTML CODE
<?php
}

Things get a little complicated here:

Replace HTML CODE with the HTML code between  and  in php.htm
Switch back to php.htm and replace the section where it says
 
with
<?php make_sidebar("right");?>

/************************************************************/
/* Function themecenterposts() */
/* */
/* Controls of various center blocks, like when you preview */
/* posts in the forum & news. */
/************************************************************/

function themecenterposts($title, $content) {
global $xoopsTheme;
?>
HTML CODE
<?php
}

Replace HTML CODE with the HTML code between  and  in php.htm

/**********************************************************************/
/* Function themeheader() */
/* */
/* This is everything that comes before stuff in the center of xoops. */
/* It's goes up to the first <td> right before center stuff appears. */
/**********************************************************************/

function themeheader($show_rblock) {
global $xoopsConfig, $xoopsTheme;
?>
HTML CODE
<?php
}

Ok, things here again get a little bit complicated:

Switch back to php.htm and replace the section where it says

with
<?php make_sidebar("left");?>
Replace HTML CODE with everything beginning from </head> and ending within  in php.htm

/*************************************************************************/
/* Function themefooter() */
/* */
/* This is everything that appears right after any center stuff. */
/* It goes includes everything before the </td> before any center stuff. */
/*************************************************************************/

function themefooter($show_rblock, $footer) {
global $xoopsTheme;
?>
HTML CODE
<?php
}

Replace HTML CODE with everything beginning from within  and ending with </body> in php.htm

/**************************************************************************/
/* OpenTable Functions */
/* */
/* The look of certain tables opend/closed in variousparts of xoops, like */
/* the tables in the center of the admin section, and in various modules. */
/**************************************************************************/

function OpenTable() {
?>
HTML CODE
<?php
}

We will copy the exact same code from function themecenterposts($title, $content) and modify it fit our needs. Below is the HTML code from themecenterposts($title, $content)

We can remove the title row as we only need the contents row as well as remove the trailing <br>:

Copy the HTML code before <?php echo $content;?> and paste that to replace the HTML CODE in function OpenTable($width="100%")

function CloseTable() {
?>
HTML CODE
<?php
}
?>

Copy the HTML code after <?php echo $content;?> as above and paste that to replace the HTML CODE in function CloseTable($width="100%")

So now we have copied and pasted all the HTML code we need for our theme files. However, we still need to add a few tweaks in order for our theme to work.

We will need to modify the footer code to allow the right block to only show when needed:

function themefooter($show_rblock, $footer) {
global $xoopsTheme;
?>
</center>
<center><?php echo $footer;?></center>
</td>
<td valign="top" width="20%">
<table style="BORDER-COLLAPSE: collapse" bordercolor="#111111" cellspacing="0" cellpadding="0" width="99%" border="0">
<tr>
<td valign="top">
<?php make_sidebar("right");?>
</td>
</tr>
</table>
</td>
</tr>
</table>
</body>
<?php
}

On the part where it says:

We will need to modify that to:

<?php if ($show_rblock) { ?>
<td valign="top" width="20%">
<table style="BORDER-COLLAPSE: collapse" bordercolor="#111111" cellspacing="0" cellpadding="0" width="99%" border="0">
<tr>
<td valign="top">
<?php make_sidebar("right");?>
</td>
</tr>
</table>
</td>
<?php }?>

This will display the 3rd column only if needed, otherwise it will only show left and centre. We also need to modify the header code to adjust the centre column to fill up the gap when the the 3rd colum is not displayed:

function themeheader($show_rblock) {
global $xoopsConfig, $xoopsTheme;
?>
</head>
<body>
<center>
<a title="Home" href="<?php echo XOOPS_URL;?>">
<img src="images/logo.jpg" border="0" width="791" height="210"></a></center>
<table style="BORDER-COLLAPSE: collapse" bordercolor="#111111" cellspacing="0" cellpadding="0" width="791" border="0" height="193" align="center">
<tr>
<td valign="top" width="20%">
<table style="BORDER-COLLAPSE: collapse" bordercolor="#111111" cellspacing="0" cellpadding="0" width="99%" border="0">
<tr>
<td valign="top">
<?php make_sidebar("left");?>
</td>
</tr>
</table>
</td>
<td valign="top" width="60%">
<center><?php if ($xoopsConfig["banners"]) { showbanner(); }?></center><br>
<center>
<?php
}

On the part where it says:

We will need to modify that to:

<?php if ($show_rblock) { ?>
<td valign="top" width="60%">
<?php } else { echo "<td valign='top' width='80%'>"; } ?>

Be careful of the ' and "

We changed the width to 80% in the else part so that it occupies the extra 20% that the 3rd column once took up.

Only one more thing to do... run a search and replace for the following on both themenews.php and theme.php:

SEARCH: images/
REPLACE WITH: <?php echo XOOPS_URL."/themes/".$xoopsTheme['thename'];?>/images/

Be sure to save all files!!! You wouldn't want to lose all that hard work...

Step 9 - Cleaning up files
Look in both themenews.php and theme.php for any HTML comments that might have been left during the editing, remove them. Also move html.htm and php.htm from the theme directory and place them somewhere safe, as we don't want anyone copying our theme.

Step 10 - Installing theme
Now that everything's done, all that's left is to install it. Upload the theme directory to the themes/ directory of your xoops. Now go into System Admin -> Preferences and change the theme then marvel at all the hard work you've done =)

Final thoughts
I spent a whole day writing this tutorial, so please drop me a message, either at my site http://mctech.f2o.org/ or email me at mC@mctech.f2o.org for any comments, suggestions and questions... Good luck with your site!

Comment name	Place to be inserted into
<!-- START LEFT BLOCK -->	Before the HTML code for left block begins
<!-- END LEFT BLOCK -->	After the HTML code for the left block, include the separating code mentioned in Step 2
<!-- START CENTRE BLOCK -->	Before the HTML code for centre block begins
<!-- END CENTRE BLOCK -->	After the HTML code for the centre block, include the separating code mentioned in Step 2
<!-- START POST BLOCK -->	Before the HTML code for post block begins
<!-- END POST BLOCK -->	After the HTML code for the post block, include the separating code mentioned in Step 2
<!-- START RIGHT BLOCK -->	Before the HTML code for right block begins
<!-- END RIGHT BLOCK -->	After the HTML code for the right block, include the separating code mentioned in Step 2

Element name	Replacement PHP code
{URL}	<?php echo XOOPS_URL;?>
{BANNER}	<?php if ($xoopsConfig["banners"]) { showbanner(); }?>
{TITLE}	<?php echo $title;?>
{CONTENT}	<?php echo $content;?>
{POSTEDBY}	<?php echo _TH_POSTEDBY;?>
{AUTHOR}	<?php echo $poster;?>
{ON}	<?php echo _TH_ON;?>
{DATE}	<?php echo $time;?>
{COUNTER}	<?php echo $counter;?>
{READS}	<?php echo _TH_READS;?>
{IMG}	<?php echo $timglink;?>
{TEXT}	<?php echo $thetext;?>
{ADMINLINK}	<?php echo $adminlink;?>
{MORELINK}	<?php echo $morelink;?>
{FOOTER}	<?php echo $footer;?>