AutoTheme
for PHP-Nuke

Version: Beta 5

Overview

AutoTheme is a Theme System script for the PHP-Nuke CMS.  I've seen many posts from new users inquiring about every aspect of the current PHP-Nuke theme system and related files.  The current theme system usually requires you to be somewhat familiar with PHP and the PHP-Nuke architecture.  AutoTheme attempts to remove most of this complexity.  If you are not very familiar with PHP and/or PHP-Nuke, don't open any of the PHP files included.  Actually, if you are a seasoned PHP and/or PHP-Nuke developer, definitely don't look at these files, they are scary (I'm a descent hack, but no developer)!

AutoTheme's primary benefit is providing users the ability to create PHP-Nuke themes in HTML using their favorite editor, with little or no use of PHP.  In addition, AutoTheme provides easy customization of block display and custom themes for different modules.

PHP-Nuke Layout

Regardless of how themes are built, a base understanding of PHP-Nuke is needed.  Standard PHP-Nuke installations make use of four main elements in the layout.  Left Blocks, Center Blocks, Right Blocks and Modules.  You can create and modify the blocks via PHP-Nuke's administration menus, but the theme controls when, where and how these four elements are displayed.  Two additional elements are used for the news, the Summary Article (displayed on the Main Page) and the Full Article (displayed when the user reads the Full Article usually by clicking Read more...).  See an example:

[ Example ]

Installation

Unzip AutoTheme into your PHP-Nuke themes/ directory.  You may safely change the name of the AutoTheme directory if you wish. You may now browse to your PHP-Nuke site and change the theme to the new AutoTheme in Administration, Settings, or start your customization.

Directory Structure

PHP-Nuke DIRECTORY
|
-----themes
        |
        -----AutoTheme
                |
                -----docs
                |
                -----images
                        |
                        -----topics
                |
                -----includes
                |
                -----style    

Example Files

AutoTheme is a Theme System, not a Theme.  The included HTML templates and images may be used as is or modified to fit your needs, but they are only examples.  You should use your own creativity to build a custom theme using the AutoTheme functionality.  The following HTML template files are included with AutoTheme and are meant to be examples of the functionality of AutoTheme.  Your site may require fewer files or more files.  You may safely delete these custom files if you wish.

The following images are included with AutoTheme in the images/ directory and are meant to be examples of the functionality of AutoTheme.  You may use fewer files or more files.  You may safely delete these custom files if you wish.

Configuration

AutoTheme looks in its directory and uses standard HTML files to display your Main Page, Left Blocks, Center Blocks, Right Blocks, Summary Articles and Full Articles.  Each HTML file contains commands, actually HTML comments that tell AutoTheme what to do.  You can configure what names to use for these files or you can modify or replace the existing templates.  If you want to change the configuration (optional), here is an explanation of the settings in theme.cfg:

[ theme.cfg ]

Theme Design

It's very easy to design AutoTheme templates.  Just use your favorite HTML editor and design a Main Page template (theme.html) and Block template (block.html).  In addition, the PHP-Nuke news module uses the theme for the two types of article displays, Summary Article (summary.html) and Full Article (article.html).  Block and Article files should not contain <html>, <head> or <body> tags.  Only the tags necessary to construct your Block or Article.

As you design your Main Page template, keep in mind the basic layout elements of a PHP-Nuke site.  The locations where these are to be placed are specified in your HTML templates using comment commands,  standard HTML comments that have an embedded AutoTheme command.  AutoTheme commands are enclosed in brackets [ ] and take the following form:

Example:    <!-- [command] -->

Here is a list and explanation of the included commands:

[ Commands ]

Cascading Style Sheets

When you build your templates you may use cascading style sheets to define the appearance of certain tags or elements.  This style sheet needs to be saved under themes/AutoTheme/style/ as style.css (main style sheet) and styleNN.css (used for Netscape navigator).  These may contain style differences but most likely will work if they are the same.  You may include your style sheet in the header of your theme template while editing, but the <link> reference will be stripped out by AutoTheme and PHP-Nuke will dynamically include one or the other depending on the viewer's browser.  As outlined in the theme.cfg example, you may also define an additional style sheet to be included after these PHP-Nuke default ones.

Images and Other Files

The base location of your PHP-Nuke page is where your PHP-Nuke index.php resides.  Therefore, images and other files such as scripts that are in a sub-directory of your AutoTheme/ directory will need to use a path relative to where the PHP-Nuke index.php resides, which is themes/AutoTheme/.  So if you have your images in the images directory an <image> tag and <script> tag would look like this:

Example:    <img src="themes/AutoTheme/images/image.gif">

Example:    <script src="themes/AutoTheme/script.js">

Two commands are available for referencing paths in your templates.  The first is for your theme directory and the second is for your theme images directory:

Command:    [theme-path]
Example:        <script src="<!-- [theme-path] -->script.js">

Command:    [image-path]
Example:        <img src="<!-- [image-path] -->image.gif">

PHP

Of course if there isn't a command for what you want to do or if you don't like the way a command functions, you can still use PHP code in your HTML templates.

Example:    <td><?php echo $some_var; ?></td>

Language Support

Language support is included with AutoTheme and is available by creating a lang-language.php in themes/AutoTheme/language/.  All text in current and future AutoTheme commands use language variables from the theme or from the main PHP-Nuke languages/.  English is included with AutoTheme in themes/AutoTheme/languages/lang-english.php.

Right-To-Left type is also supported and is automatically activated when the user's language is a RTL language.  Arabic and Hebrew are currently supported.  If you know of other RTL languages, send them to me and I will include in the next release.

Additional Functionality

Custom Block Templates

Every block has a unique name that is configured in PHP-Nuke Administration / Blocks.  By configuring the values in theme.cfg for specific blocks by name, you can define custom templates that are used only for that specific block.  The old style looked for an HTML template (.html, .htm, .php) with the same name as the block and used that as the template.  Images for custom block titles were treated in the same fashion (gif, jpg, png).  Now to have a custom block title image, include that image in the custom block template.

Displaying Blocks

The theme.cfg contains settings for each type of block that lets you determine when to display the block.  You may display the block on all pages or just the main page.

Custom Modules

Every module has a unique name that is configured in PHP-Nuke Administration / Modules.  By configuring the values in theme.cfg for specific modules by name, you can define custom templates, style sheet, image and colors that are used only for that specific module.  In addition, you can control what blocks are displayed on a per module basis.

Block Ideas

Since you are creating your own templates for the Main Page and for the blocks, then you have a lot of flexibility.  Traditional PHP-Nuke sites display their blocks vertically.  With AutoTheme it's very easy to display them horizontally.  Let's say in your Main Page template you have a <td>, if you put a <table> in that <td> then your block templates can be <td>s inside of that <table>.  So each new block creates a <td> which will be next to the previous <td> until you define a new row <tr>.  This same affect may be acheived if your blocks are tables by setting align="left" which is analogous to floating left.

Extending AutoTheme

The most common commands used in PHP-Nuke themes are already available, but AutoTheme can be easily extended by adding additional AutoTheme commands and the associated PHP statements or PHP-Nuke functions that the commands execute.  Commands  are defined in themes/AutoTheme/includes/commands.inc.php.

Bugs and Feedback

Please send bug reports or feedback to abracadaver@mckenzies.net or visit http://spidean.mckenzies.net


AutoTheme is Free Software released under the GNU/GPL license.