-
Notifications
You must be signed in to change notification settings - Fork 1
Creating_a_theme_from_scratch
Cameron edited this page Jan 28, 2017
·
1 revision
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
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.
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.
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
}} ### 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. ### 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). ### Language Information - 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. - 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). ### IMODE So that your theme renders correctly, set the IMODE to **lite** or **dark**. This ensures that theme images are displayed properly. ### 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. ### 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 definition The name of the layout to be used by your template. The layout is responsible for an header (, , , , ...) and a footer ( , , .... ). 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](http://e107.org/e107_plugins/forum/forum_viewtopic.php?218774) #### $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. 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](/Theming_Custom_Pages "wikilink"). **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. - {$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](/Theming_Menus "wikilink") ### 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. - {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](/Theme_Image_Usage "wikilink") setting. - {NEWSICON} - - {NEWSTITLE} - - {NEWSTITLELINK} - - {NEWSBODY} - - {EXTENDED} - - {NEWSAUTHOR} - - {NEWSDATE} - - {NEWSCOMMENTS} - - {TRACKBACK} - - {EMAILICON} - - {PRINTICON} - - {PDFICON} - ensure that the [PDF Plugin](/PDF_plugin "wikilink") is installed. - {ADMINOPTIONS} - Here again you could make a lot of variation to the News Render Style using [modifiers](/Enhanced_news_style "wikilink"). ### Link Style Link style defines how your **Site Links** will be displayed. - 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:**| PRELINK | LINKSTART | Link1 | LINKEND | LINKSTART | Link2 | LINKEND | POSTLINK |