Creating a theme from scratch

English | Magyar | Русский

Objective

The objective of this article is to guide the reader through how to create a fully functional e107 theme from scratch minus the visual appeal.

It covers all the basic 'core code' default css styles used.

Anyone creating a theme (or editing an existing one) is highly recommended to install Firefox as their Web Browser and the Web Developer Tool Bar extension which will make viewing and editing your project so much easier

NOTE: This article covers versions 0.7+ of e107.

Theme overview

Basic Theme

Themes must have a theme.php, a style.css, a blank index.html for security and an image folder containing your images.

Theme.php

This contains the main design of your external site.

Style.css

This contains the stylesheet information used by the various html elements used in e107.

Images Folder

The folder contains all the images used in your theme.

Languages Folder

If you are designing a multi-language theme, it will contains at least one language file, where you place translated item codes for use in theme.php

Theme Templates

e107 uses Template Files to format specific types of content provided by core features and plugins, i.e. downloads, links, login search, forum etc. Many themes simply use the defaults provided with e107, but you can include customised versions in your theme folder to get finer control.

The default templates should remain unchanged in the e107_themes > templates folder, so that your changes are not lost at upgrade.

Plugin which provide templates, such as, forum, chat, content manager, store them in the e107_plugins/plugin_name folder. The default templates provide the standard layout for the plugin.

You can copy any templates into your theme folder and code away at them to change the look of your site. e107 first checks your theme folder for a template to use. When your theme does not contain a template, then the default template will be used instead. This means you can make your site as individual as you like without any of your work getting overwritten by future updates.

The templates generally consist of tables to control the layout of a page. Lamb theme, for example, contains a news_template.php file which splits the news into 2 columns. You can copy that into most themes to use to get the same effect.

Theming Forum Icons: One of the things that lets down most themes is that few developers bother to mod the templates to match or add different images from the standard ones. Create a folder in your theme called forum and drop the images into that. As long as they have the same filename as the core ones, then e107 will again override the core.

Step 1) File and Folder Structure

An e107 theme usually has the following directory structure:

- e107_themes (dir)
  ↓
  + my_theme  (dir)
    ↓
    + images  (dir)
    ↓    ↓ 
    ↓    + bullet.png
    ↓    + other_images.jpg
    ↓    + index.html
    ↓
    + languages (dir)         (Optional)
    ↓    ↓
    ↓    + English.php
    ↓    + index.html
    ↓
    + preview.jpg
    + theme.php
    + style.css
    + index.html   
    ↓
    + theme.js OR theme-js.php      (Optional)
    + favicon.ico                   (Optional)
    + any_templates.php             (Optional)
    + forum (dir)             (Optional)
         ↓
         + (custom forum image set)

• e107_themes - Theme folder of your e107 installation.
• my_theme - The name of your theme.
• languages - Contains different translations of text found in your theme. Ex. Comments, Trackbak, etc.
• images - Contains all the images used by your theme.
• bullet.png - Bullet to be used by your theme.
• preview.jpg - A small image preview of your theme. Ideal size is 200px by 150px.
• theme.php - Main theme file. (Ensure this is a php formatted file and not just a text file)
• style.css - Contains all the styles used by your theme.
• theme.js OR theme-js.php - if your theme needs Javascript, use one of these files to contain the script (as above, if you use a php file it must be formatted as such).
• favicon.ico - if your theme has its own favicon store it here (NOT in the images directory) - e107 will pick it up and display it automatically.
• index.html - Usually a blank file. This is added for security reasons.

Create the above structure before proceeding to the next sections. If you don't have images to use immediately, copy them from another theme.

Step 2) Create Theme.php

Please review Developer Tools and Tips for e107, using notepad or wordpad will break your system, choose a unix compatible text editor.

PHP Open

The theme is a php page, hence we need the opening <?php tag.

<?php

Copyright Information

All good programs will include basic information about the code, its purpose, licensing and about the author. These are included using the comment tags for the particular language you are using. In the case of PHP commenting a block uses the /* and */ to close the comment. For ease of reading, you will find underscores and pipes are used to make lines, these are simply used to format the code nicely. If it is your theme design, feel free to add your details to the copyright information.

/*
+ ----------------------------------------------------------------------------+
|     e107 website system
|
|     Copyright (C) 2001-2002 Steve Dunstan (jalist@e107.org)
|     Copyright (C) 2008-2010 e107 Inc (e107.org)
|
|
|     Released under the terms and conditions of the
|     GNU General Public License (http://gnu.org).
|
|     $URL$
|     $Revision$
|     $Id$
|     $Author$
+----------------------------------------------------------------------------+
*/

Theme Security

Next we need the security check if (!defined('e107_INIT')) { exit; }. It is the needed in any code file which is not intended to be opened directly in a user's browser - prevents users from executing files in unintended ways (which could breach security).

    if(!defined("e107_INIT")){ exit; }

Language Information

    // [multilanguage]
    include_lan(e_THEME."my_theme/languages/".e_LANGUAGE.".php");

• Make sure to change the "my_theme" to the name of your theme's folder.

Theme Information

The following variables are used by e107 Plugin Manager, to tell you information about the theme. Fill in and adapt to your own theme.

    // [theme information]
    $themename = "My Theme";
    $themeversion = "1.0";
    $themeauthor = "Juan dela Cruz";
    $themeemail = "juan@mytheme.com";
    $themewebsite = "http://mytheme.com";
    $themedate = "April 6, 2006";
    $themeinfo = "This theme is originally done by me."; 
    
    // Compliance Information
    // Only set if you have verified these are true - getting these wrong can affect your seo.
    $xhtmlcompliant = TRUE;
    $csscompliant = TRUE;

• Replace the values with the information pertaining to your theme.

All of these switches are shown next to the theme on the Theme Manager Plugin page, so please be as verbose as you like, especially with the $themeinfo switch.

One other point, if you're making a multi-language theme, you must leave the text in these switches in the theme.php, and not in the language file.

Including Scripts

If your theme uses Javascript that is specific to the theme (rather than being part of e107's own Javascript files) then you must place your scripts into either theme-js.php or theme.js (see File and Folder Structure above).

 define('THEME_ONLOAD','MyJSinit();');     // Initialize JavaScript code at page load time

IMODE

So that your theme renders correctly, set the IMODE to lite or dark. This ensures that theme images are displayed properly.

 define("IMODE", "lite");

User Width

Instead of hardcoding 95% and 98% table widths into core files, USER_WIDTH has been added into many of the files and templates. Meaning, that if you put: define("USER_WIDTH","width:100%"); or any other width you care to specify into your theme.php, it will over-ride the default setting and make internal tables go right to the edge of the layout that they're in, rather than leave a space. The default settings are still in so that current behaviour will continue if USER_WIDTH is not defined for backward compatibility.

 define("USER_WIDTH","width:100%"); 

Layout

The layout of your theme draws the basic outline of your website. The default layout is normally defined first. Layouts are used by the Menu Manager. You can have multiple layouts in a theme.

The layout is split into two sections:

• $HEADER - The top and left of the site.
• $FOOTER - The right and bottom.

All the content like news, forum, articles, etc. are placed in automatically by e107 between the $HEADER and $FOOTER variables.

To demonstrate, here is an example layout we then create with the code below.

-------------------------------
  W e b s i t e   T i t l e
  S i t e   T a g   L i n e 
------------------------------- 
Site Links 
-------------------------------
Menu 1 ¦ M a i n 
       ¦ C o n t e n t 
       ¦ A r e a
-------------------------------
 S i t e   D i s c l a i m e r
-------------------------------

The example layout is named _default. It starts with a main table for holding the website content. The first table row contains one table cell, for displaying the website name and website tagline. The next row contains your Site Links. In the next row there's a left column containing one menu area. The main content is slotted in after this. The footer area, closes the main content section, does not have a right column. The site is then closed with the last row containing the disclaimer section. So here is the code for the example layout.

    // [layout]
    $layout = "_default";

    $HEADER = "
<table>
    <tr>
        <td colspan='2'>
            <h1>{SITENAME}</h1>
            <h2>{SITETAG}</h2>
        </td>
    </tr>
    <tr>
        <td colspan='2'>
            {SITELINKS}
        </td>
    </tr>
    <tr>
        <td>
             {MENU=1}
        </td>
        <td>";

 // Main Content is placed here between the header and footer.

    $FOOTER = "
        </td>
    </tr>
    <tr>
        <td colspan='2'>
            {SITEDISCLAIMER}
        </td>
    </tr>
</table>";

$layout definition

The name of the layout to be used by your template. The layout is responsible for an header (<doctype>, <html>, <head>, <body>, ...) and a footer ( </body>, </html>, .... ).

The default value for $layout is "_default" and it loads the header_default.php and footer_default.php; if you set $layout to "_XXX" then header_XXX.php and footer_XXX.php will be loaded. e107 looks for these files in your theme folder and then in e107_themes\templates (so: files in your theme folder override those in e107_themes\templates) .

If you wish to code your own header and footer, copy them in your theme folder and edit them. By the way, before doing so, ask yourself if you really have to do it: it requires a deeper insight in e107 and most can be achieved via multiple $CUSTOMHEADER and $CUSTOMFOOTER in theme.php in combination with style.css these days, which is far better for future core upgrades.

• See also [1]

$HEADER

• This is where your html layout starts.
• The html tags here will be placed right after the body tag.

Shortcodes used in the header

Shortcodes are used to include preference values or other custom code into your theme. In this example, the following are included in the layout header.

• {SITENAME}
  • This will be replaced with your actual site name set by your preferences.
• {SITETAG}
  • Returns the current 'site tag' as configured in preferences.
• {SITELINKS}
  • This shortcode will be replaced with the main site links.
  • Formatting of the sitelinks is discussed on a later section.
• {MENU=1}
  • This will be replaced by all the menus active at menu area 1.
  • You can also apply different formatting on each menu and that is discussed on a later section.

$FOOTER

This displays everything after the main content. It needs to close all your html tags opened in the $HEADER variable.

Shortcodes used in the footer

• {SITEDISCLAIMER}
  • This displays the disclaimer you placed in your site preferences.

Custom Pages

Custom pages allow heterogeneity within your e107 powered website. For example you can have a 'three column layout' for your news page, a 'one column layout' for your signup page and a 'two column layout' for your forum pages using custom pages/layouts. There are virtually no limits to the number of Custom Pages you can create.

Custom pages are structured and made to work the same way as your Default Layout. The difference is that $HEADER and $FOOTER is denoted as $CUSTOMHEADER and $CUSTOMFOOTER and the markup defined in it will only be used to pages that you define in the $CUSTOMPAGES variable.

$CUSTOMHEADER['my_layout'] = "
    <table>
        <tr>
            <td>
                <h1>{SITENAME}</h1>
                <h2>{SITETAG}</h2>
            </td>
        </tr>
        <tr>
            <td>
                {SITELINKS}
            </td>
        </tr>
        <tr>
            <td>
";

$CUSTOMFOOTER['my_layout'] = "
            </td>
        </tr>
        <tr>
            <td>
                {SITEDISCLAIMER}
            </td>
         </tr>
    </table>
";

$CUSTOMPAGES = "forum.php forum_post.php forum_viewforum.php forum_viewtopic.php user.php 
submitnews.php download.php links.php stats.php usersettings.php signup.php";

You usually use custom pages if you have different designs/layouts for different pages. To know more about defining more than one set of custom page please read this article.

As of e107 v2.0+ the use of $CUSTOMHEADER and $CUSTOMFOOTER is deprecated. In 2.0+ themes all layouts (including the default one) should use $HEADER['my_layout_name'] and $FOOTER['my_layout_name']. Old themes will work, but for best results, just use $HEADER and FOOTER arrays.

Table Render Style

This portion tells e107 how to draw nearly all the inner layouts inside your outer layout/s. Outer layouts consist of both Default Layout and Custom Layout/Pages.

Table Render Style function decides the layouts for your menu blocks, main content block (different e107 core pages, plugin pages etc) and many layouts in the Admin pages.

//[tablestyle]

function tablestyle($caption, $text){
        echo "<h3>{$caption}</h3>
              <div>{$text}</div>";
} 

• {$caption} - This is the caption/title of the menu or page. This variable will be replaced with the actual name of the menu or page.
• {$text} - This is the content of the menu or page. This variable will be replaced with the actual content of the menu or page.

One could make a lot of variation to the Table Render Style function to make it render/draw the layout differently for different e107 component that uses it. One example is styling individual menus

News Render Style

This part simply tells e107 how to draw your news items. You can put your markup for rendering your news item here.

A news item essentially has three components a ‘News Title’, a ‘News Body’ and an ‘Extended News Body’ these are printed inside your markup using shortcodes that are predefined for it. Apart from those three components e107 news system allows you to render other information too using predefined shortcodes, they are ‘News Author’, ‘News Date’, ‘News Comments’, ‘News Icon’ ‘Sticky Icon’ etc.

You could also add custom defined shortcodes in news style or many other places in your theme.php but that is beyond the scope of this article and will be discussed elsewhere.

//[newsstyle]
$NEWSSTYLE = "<h3>{NEWSTITLE}</h3>
              <div>{NEWSBODY}<br />
                   {EXTENDED}</div>";

• {STICKY_ICON} - This front end news style shortcode will be replaced by the 'sticky.png' image, either from e107_images\generic\lite or e107_images\generic\dark directory depending on your theme's IMODE setting.

• {NEWSICON} -
• {NEWSTITLE} -
• {NEWSTITLELINK} -
• {NEWSBODY} -
• {EXTENDED} -
• {NEWSAUTHOR} -
• {NEWSDATE} -
• {NEWSCOMMENTS} -
• {TRACKBACK} -
• {EMAILICON} -
• {PRINTICON} -
• {PDFICON} - ensure that the PDF Plugin is installed.
• {ADMINOPTIONS} -

Here again you could make a lot of variation to the News Render Style using modifiers.

Link Style

Link style defines how your Site Links will be displayed.

//[linkstyle]
define('PRELINK', "<ul>");
define('POSTLINK', "</ul>");
define('LINKSTART', "<li>");
define("LINKSTART_HILITE", "<li class='hilite'>");
define('LINKEND', "</li>");
define('LINKDISPLAY', 1);
define('LINKALIGN', "left");

• PRELINK - Place in front of the entire site links section. Usually contains opening table, div, or ul. This define can be blank.
• POSTLINK - Place at the end of the entire site links section. Usually contains closing table, div, or ul. This define can also be blank.
• LINKSTART - HTML tag in front of each link.
• LINKSTART_HILITE - HTML tag in front of the active link.
• LINKEND - HTML tag at the end of each link.
• LINKDISPLAY - 1: Along top, 2: In left or right column
• LINKALIGN - Link text alignment.

Link style illustration:

• See Also: Styling Individual Sitelink Menus

Comment Style

This is how the comments will be displayed on your site. There are 13 shortcodes, a description of them can be found at Shortcodes:Comments. This is setup just like the other styles, first you start with "$COMMENTSTYLE", then the rest is up to you :).

$COMMENTSTYLE = "
<table style='width:100%'>
<tr>
<td colspan='2' class='forumheader3'>
{SUBJECT}
<b>
{USERNAME}
</b>
|
{TIMEDATE}
</td>
</tr>
<tr>
<td style='width:30%; vertical-align:top'>
<div class='spacer'>
{AVATAR}
</div>
<span class='smalltext'>
{COMMENTS}
<br />
{JOINED}
</span>
<br/>
{REPLY}
</td>
<td style='width:70%; vertical-align:top'>
{COMMENT} {COMMENTEDIT}
</td>
</tr>
</table>
<br />";

Advanced Comment Styling

For more control over the comment area you can add a comment_template.php. Find the file:-

/e107_themes/templates/comment_template.php

If you don't have one copy the template to your theme folder such as :-

/e107_themes/my_theme_name/comment_template.php

Chatbox Style

Rather easy, there are only 3 shortcodes (you can find them listed at Shortcodes:ChatBox). You need to start with "$CHATBOXSTYLE", then you can format it any way you wish.

$CHATBOXSTYLE = "
<img src='".THEME_ABS."images/bullet2.gif' alt='bullet' />
<b>{USERNAME}</b><br />{TIMEDATE}
<div class='smalltext'>
{MESSAGE}
</div>
<br />";

Closing

Finally, make sure you've enclosed all of the php code in the proper opening and closing tags:

<?php
    //theme.php code
?>

More On Theming

• Advanced theme creation
• Theming

Step 3) Creating style.css

"Cascading Style Sheets (CSS) is a style sheet language used to describe the presentation semantics (the look and formatting) of a document written in a markup language." [2]

All e107 Themes must contain a file called style.css, this contains the style information about the classes used by the e107 Core and those you can define yourself in your custom theme.

Core classes will take their style properties from the values you set in style.css of your theme. You can change the characteristics of the class for the by changing the settings for the item class, such as, font, colour, size and so forth.

A good start would be to copy an existing style.css from another theme, so that you ensure you have most of the classes used and to be personalised for your own use on your website.

e107 Core CSS Classes

• button
• defaulttext
• fborder
• fcaption
• forumheader
• forumheader2
• forumheader3
• indent
• installed
• login
• pass
• smalltext
• mediumtext
• tbox
• tbox
• search
• user

Classes that occur in Templates

button

• admin_template.php
• banner_template.php
• bbcode_template.php
• comment_template.php
• contact_template.php
• download_template.php
• email_template.php
• footer_default.php
• fpw_template.php
• header_default.php
• login_template.php
• membersonly_template.php
• online_template.php
• search_template.php
• signup_template.php
• sitedown_template.php
• trackback_template.php
• user_template.php
• userposts_template.php
• usersettings_template.php

link_button

• links_page - links_template.php

small

Also found in

*Alt_Auth - alt_auth_conf.php

*Banner_Menu - config.php

*Blogcalendar_Menu - config.php

*Calendar_Menu - admin_config.php , calendar_shortcodes.php , calendar_template.php , event.php

*Chatbox_Menu - admin_chatbox.php , chat.php , chatbox_menu.php

*Clock_Menu - config.php

*Comment_Menu - config.php

*Content - content_class.php , content_form_class.php , content_preset.php

*Featurebox - admin_config.php

*Forum - forum.php , forum_admin.php , forum_conf.php , forum_post.php , Forum_post_shortcodes.php , forum_uploads.php , forum_viewforum.php , Forum_viewtopic.php , newforumposts_menu_config.php , forum_post_template.php

*Gsitemap - admin_config.php

*Integrity_Check - admin_integrity_check.php

*Links_Page - link_class.php , links_template.php

*Linkwords - admin_config.php

*List_New - admin_list_config.php

*Log - admin_config.php

*Login_Menu - config.php , login_menu_shortcodes.php

*Newforumposts_Main - admin_config.php

*Newsfeed - admin_config.php

*Newsletter - admin_config.php , newsletter_menu.php

*Pm - pm_conf.php , pm_shortcodes.php , private_msg_menu.php

*Poll - poll_class.php

*RSS_menu - rss_shortcodes.php , rss_template.php

*Search_Menu - search_menu.php

*Trackback - admin_config.php , modtrackback.php

*Tree_Menu - config.php

*Userlanguage_Menu - userlanguage_menu.php

*Usertheme_menu - usertheme_menu.php

defaulttext

• banner_template.php
• download_template.php
• signup_template.php
• usersettings_template.php

Also found in

*Calendar Menu - calendar_template.php

*Chatbox Menu - chat _template.php

*Featurebox - centered.php , default.php

*Forum - forum_post_shortcodes.php , forum_posted_template.php

fborder

• banner_template.php
• comment_template.php
• download_template.php
• footer_default.php
• fpw_template.php
• login_template.php
• membersonly_template.php
• online_template.php
• search_template.php
• signup_template.php
• user_template.php
• userposts_template.php
• usersettings_template.php

fcaption

• banner_template.php
• download_template.php
• footer_default.php
• fpw_template.php
• trackback_template.php
• user_template.php
• userposts_template.php

forumheader

• banner_template.php
• comment_template.php
• download_template.php
• fpw_template.php
• login_template.php
• online_template.php
• signup_template.php
• user_template.php
• userposts_template.php
• usersettings_template.php

forumheader2

• login_template.php
• usersettings_template.php

forumheader3

• banner_template.php
• download_template.php
• footer_default.php
• fpw_template.php
• login_template.php
• membersonly_template.php
• online_template.php
• search_template.php
• signup_template.php
• user_template.php
• userposts_template.php
• usersettings_template.php

installe

• header_default.php

smalltext

• comment_template.php
• download_template.php
• footer_default.php
• login_template.php
• signup_template.php
• userposts_template.php
• usersettings_template.php

tbox

• contact_template.php
• download_template.php
• fpw_template.php
• signup_template.php

tbox search

• search_template.php

Classes appearing in e107.css

table (element)

searchhighlight

defaulttable

fbdefault

fdefault

f2default

f3default

fcdefault

center

right

left

day

dayentry

forumheader4

forumheader5

ul