Creating an e107 theme

Theme Overview

  • e107 v2.x is designed for Bootstrap styling. It is therefore encouraged for developers to use bootstrap as their guide for their HTML markup.
  • A default Bootstrap 3 is provided with e107. For html markup and examples, please refer to the Bootstrap documentation and for snippets: bootsnipp.com.
  • If you find markup in the core templates of e107 which does not work well with bootstrap, please let us know in the Github issue tracker, so that we may correct it.

theme.xml

This file contains information about the theme. It is used during installation and also during configuration of the theme.
To create a new theme.xml file or derive one from an existing v1.x theme.php file use the conversion tool here: yoursite.com/e107_admin/theme.php?mode=convert
Example from the bootstrap theme: 

		<?xml version="1.0" encoding="utf-8"?>
<e107Theme name="bootstrap" version="1.0" date="2012-12-01" compatibility="2.0">
    <author name ="e107 Inc" email="@" url="http://e107.org" />
    <summary>Bootstrap e107 admin theme</summary>
    <description>Bootstrap e107 admin theme</description>
    <category>generic</category>
    <keywords>
        <word>bootstrap</word>
        <word>clean</word>
    </keywords>
    <screenshots>
        <image>preview.jpg</image>
        <image>fullpreview.jpg</image>
    </screenshots>
    <stylesheets>
        <css file="style.css" name="Default"  />
        <css file="css/superhero.css" name="Superhero" />
    </stylesheets>
    <layouts>
        <layout name='default' title='Default' default='true' />
        <layout name='default-home' title='Default Home'>
            <custompages>FRONTPAGE</custompages>	
        </layout>
        <layout name='hero' title='Hero' />
        <layout name='marketing-narrow' title='Marketing Narrow' />
        <layout name='docs' title='Documentation' />
    </layouts>
</e107Theme>
Tip: If you are developing a commercial theme, you'll want to add a few extra attributes so that it displays correctly in the admin area under "Find Themes". .

<e107Theme name="bootstrap" ... <strong>price="25.00" currency="EUR" url="http://direct-path-to-my-theme-purchase-page.com"</strong> >

Just package your theme's zip file with only the theme.xml and any images (including screenshots) , excluding .php, .css files etc. before sharing it.
When the user clicks to download the theme, it will display the url you have provided.

theme.php

Contains the main HTML template for your theme. A very basic theme.php file might look like this example below. the {---} is replaced automatically with the main page's content. 
<?php

$LAYOUT['default'] = "
        <header>MY HEADER<header>
        <article>
            {---}
        </article>
    <footer> My Footer </footer>
";

function tablestyle($caption, $text, $mode='') 
{
    echo "<h3>".$caption."</h3>";
    echo $text;
}

?>
e107 will take this data and render the dynamic content of the page into it. The output of the above might look something like this: 
<html>
<head>
 // Auto generated title, script, meta and link tags are added here. 
</head>
<body>
    <header>MY HEADER<header><article>
    <h3>Caption of the current page</h3>
    Text of the current page
    </article><footer> My Footer </footer>
</body>
</html>

Including JS, CSS and Meta in the head

See the section on including Javscripts, Stylesheets and Meta information.

Including a language file

You should use core language terms and avoid using a theme language file if possible. Refer to e107_languages/English/English.php for available terms. 
e107::lan('theme'); // loads e107_themes/CURRENT_THEME/languages/English.php (when English is selected)

Core Shortcodes

Commonly used core theme shortcodes are listed below.

Name Description
{---} Renders the main content of the current page.
{CMENU=xxxxxx} Renders a specific custom menu item as defined in admin -> Pages/Menus. xxxxxx = menu name.
{LOGO} The site's logo as defined in the admin preferences.
{MENU=1} Menu Area as allocated using the media-manager in admin. Add multiple areas by incrementing the numeric value.
{MENU: type=xxxxxx} When xxxxxx is NOT a number, it will attempt to render a specific menu with the name xxxxxx. eg. {MENU=contact} will render e107_plugins/contact/contact_menu.php
{NAVIGATION=xxxxx} Bootstrap-style navigation. Where xxxxx is one of: main, side, footer, alt, alt5, alt6 eg. {NAVIGATION=footer}
{SETSTYLE=xxxxxx} A special shortcode which is used to dynamically change the value of $style as used inside tablerender() to the value of xxxxxx.
{SETIMAGE: w=x} A special shortcode which is used to dynamically change the size of avatars and other images. x= numerical value. eg. {SETIMAGE: w=100&h=200&crop=1}
{SITEDESCRIPTION} The description of the website as defined in the admin preferences.
{SITEDISCLAIMER} The site disclaimer as defined in the admin preferences. Typically used in the footer of the site.
{SITENAME} The name of the website as defined in the admin preferences.
{WMESSAGE} Renders the welcome message as defined in admin-> Welcome Message.



Usage example: 

		$LAYOUT['default'] = "
    <header>{SITENAME}<header>
    <div>{NAVIGATION=main}</div>
    {SETSTYLE=menu}
    <div class='span2'>
    {MENU=1}
    {MENU=contact}
    </div>
    <div class='span10'>
    {SETSTYLE=default}

 {---}

    </div>
    <footer>{SITEDISCLAIMER}</footer>
";

function tablestyle($caption, $text, $mode='')
{
    global $style; // value defined by {SETSTYLE} shortcode. 
 
    switch($style) 
     {
        case 'menu': 
            echo "<h5>".$caption."</h5>";
            echo $text;
        break;

        default: 
            echo "<h2>".$caption."</h2>";
            echo $text;
        break;
    }
    
}

News


Shortcode Description Optional Parameters
{NEWS_ID} Unique ID for the current news item (news_id)
{NEWS_TITLE} News Title
{NEWS_SUMMARY} News item summary
{NEWS_DATE} News Date
{NEWS_BODY} News Body (main content)
{NEWS_TAGS} New Keywords/Meta-Keywords
{NEWS_URL} News URL (current URL)
{NEWS_AUTHOR} Name of the Author of the news item
{NEWS_AUTHOR_AVATAR} Avatar of the Author of the news item
{NEWS_AUTHOR_SIGNATURE} Signature text of the Author of the news item. eg. a short bio about the user.
{NEWS_AUTHOR_ITEMS_URL} Link to a News page listing all items by the same author.
{NEWS_CATEGORY_NAME} News Category Name
{NEWS_CATEGORY_DESCRIPTION} News Category Description
{NEWS_CATEGORY_ICON} News Category Icon
{NEWS_RELATED} Related news items based on keyword matches types: news | page
limit: (integer) (default is 5)

Page/Menu


Shortcode Description Optional Parameters
{CPAGEANCHOR}
{CPAGETITLE} Title of the page
{CPAGEBODY} Main text body of the page
{CPAGEAUTHOR} Author of the page
{CPAGEDATE} Creation date of the page {CPAGEDATE=x} default: long. 'short' and 'relative'
{CPAGEMETADIZ} Meta description of the page.
{CPAGEBUTTON}
{BOOK_ANCHOR}
{BOOK_DESCRIPTION}
{BOOK_ICON}
{BOOK_ID}
{BOOK_NAME}
{BOOK_URL}
{CHAPTER_ANCHOR}
{CHAPTER_BREADCRUMB}
{CHAPTER_BUTTON}
{CHAPTER_DESCRIPTION}
{CHAPTER_ICON}
{CHAPTER_ID}
{CHAPTER_NAME}
{CHAPTER_URL}

style.css

This file should contain the primary css for your theme.
Keep in mind that e107 v2.x uses bootstrap naming conventions.

theme_shortcodes.php

OPTIONAL e107 v2.x removes the need for separate xxxxxx.sc files inside your theme's folder. You can now include all your theme-specific shortcodes in a single file. These shortcodes may be used in the $LAYOUT of your theme.php file. eg. Using the example below: {MY_SHORTCODE} and {MY_OTHER_SHORTCODE}

		class theme_shortcodes extends e_shortcode
{
	
    function sc_my_shortcode()
    {
        return "Something";
    }

    function sc_my_other_shortcode()
    {
        return "Something else";
    }

}

theme_config.php

OPTIONAL Adds information and user-selectable options to the theme's configuration page.

		class theme_mytheme implements e_theme_config
{
    function process() // Save posted values from config() fields. 
    {
        $pref = e107::getConfig();
		
        $theme_pref 					= array();
        $theme_pref['example']			= $_POST['_blank_example'];
        $theme_pref['example2'] 	= intval($_POST['_blank_example2']);

        $pref->set('sitetheme_pref', $theme_pref);
        return $pref->dataHasChanged();
    }

    function config()
    {
        $tp = e107::getParser();
		
        $var[0]['caption'] = "Sample configuration field";
        $var[0]['html'] = $tp->text('_blank_example', e107::getThemePref('example', 'default'));

        $var[1]['caption'] = "Sample configuration field";
        $var[1]['html'] = $tp->text('_blank_example2', e107::getThemePref('example2', 'default'));
		
        return $var;
    }

    function help()
    {
        return "
                <div class='well'>
                        Some information about my theme. 
                </div>
        ";
    }
}

Overriding Core Templates

  • All templates that are used in e107 can be overridden by copying them into specific folders within your current theme folder. 
  • Core themes (located in e107_core/templates/ ) should be copied into e107_themes/YOURTHEME/templates/ 
  • Plugin templates should be copied into e107_themes/YOURTHEME/templates/PLUGIN-FOLDER
    Note: Older plugins may look for templates in the root folder of your theme. ie. e107_theme/YOURTHEME/  

Some examples to illustrate this:
1) The comment template is a core template, as it is located in e107_core/templates/. To override this template, copy the file to e107_themes/your_theme_folder/templates/.

2) The news template is located in e107_plugins/news/. To override this template, copy the file over to e107_themes/your_theme_folder/templates/news/.

3) The same for, for example, the chatbox menu template. The chatbox_menu template is located in e107_plugins/chatbox_menu. Copy the template over to e107_themes/your_theme_folder/templates/chatbox_menu/

Important: For overriding plugin templates, the folder name within your_theme_folder/templates/ directory must match the exact plugin folder name. 

Upgrading v1.x Themes

Themes developed for v1.x of e107 will continue to work using v2.x. However, to get the most out of v2.x, we suggest the following changes be made to bring your theme up to the new v2.x standards. Replace $HEADER and $FOOTER with $LAYOUT['default'] combining both of them into a single template. Place a {---} between them so e107 knows where to split it into HEADER and FOOTER. Replace any occurrences of $CUSTOMHEADER and $CUSTOMFOOTER with $LAYOUT['custom'] (see above) If you have recurring code in your $LAYOUT. eg. Navigation html which should be included as the header and footer of every layout, then use the special layouts: $LAYOUT['_header_'] and $LAYOUT['__footer_']. If your theme contains links to external social pages such as facebook, twitter, youtube or google+, use the core definitions for them. ie. XURL_FACEBOOK, XURL_TWITTER, XURL_YOUTUBE, XURL_GOOGLE. Remove any reference to $CUSTOMPAGES and place them inside theme.xml in the layouts section. 
<layout name='custom' title='Custom Pages'>
    <custompages>FRONTPAGE</custompages>
    <custompages>/forum/</custompages>
</layout>
If you have used index.php in your $CUSTOMPAGES list, use FRONTPAGE instead (see above) The function theme_head() has been deprecated. Instead, use either e107::css() or e107::js() to include what you require in the header. (see bootstrap or other new core theme for examples) Shortcodes need to be set to UPPERCASE in all occurrences in your theme.php file. Remove all references to $register_sc['xxxxx'] from theme.php for shortcodes used in the $LAYOUT. Place the contents of all xxxxxx.sc files used by $LAYOUT ($HEADER and $FOOTER) inside theme_shortcodes.php and then remove these xxxxxx.sc files from your theme's folder.

Social Links