Creating a theme from scratch
e107 Wiki: English | Русский | Deutsch | Français | Magyar | Português | Български | Česky | Nederlands | Ελληνικά | Italiano | Norske | Polska | Slovenščina | Español | Svenska | Translate: Wiki | Page
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.
Themes must have a theme.php, a style.css, a blank index.html for security and an image folder containing your images.
This contains the main design of your external site.
This contains the stylesheet information used by the various html elements used in e107.
The folder contains all the images used in your theme.
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
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)
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.
The theme is a php page, hence we need the opening <?php tag.
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.
Next we need the security check if
The following variables are used by e107 Plugin Manager, to tell you information about the theme. Fill in and adapt to your own 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.
So that your theme renders correctly, set the IMODE to lite or dark. This ensures that theme images are displayed properly.
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.
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:
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.
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.
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.
This displays everything after the main content. It needs to close all your html tags opened in the $HEADER variable.
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.
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.
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.
Here again you could make a lot of variation to the News Render Style using modifiers.
Link style defines how your Site Links will be displayed.
Link style illustration:
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 :).
Advanced Comment Styling
For more control over the comment area you can add a comment_template.php. Find the file:-
If you don't have one copy the template to your theme folder such as :-
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.
Finally, make sure you've enclosed all of the php code in the proper opening and closing tags:
More On Theming
Step 3) Creating style.css
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
Classes that occur in Templates
Classes appearing in e107.css