Installation & configuration

Please note: This page is under construction and has not been finished yet.

Introduction

TODO:

• overview of install & config files (theme.xml & theme_config.php)

• highlight some options

• refer to example themes (bootstrap3)

theme.xml

This file contains information about the theme. and is used during installation and also during configuration of the theme.

👍 TIP: To create a new theme.xml file or derive one from an existing v1.x theme.php file use the conversion tool in the Admin Area > Theme Manager > Tools (/e107_admin/theme.php?mode=convert)

Please note: Unlike plugin.xml, the theme.xml file is not intended to replace the theme.php file. Instead, theme.xml works alongside theme.php to provide (meta)data about the theme itself.

Example#1: Full theme.xml

The below example uses the theme.xml from the Bootstrap3 theme included in e107 by default. Each section of the XML file is elaborated upon below.

<?xml version="1.0" encoding="utf-8"?>
<e107Theme name="Bootstrap 3" version="1.0" date="2013-12-25" compatibility="2.0">
	<author name="e107 Inc" email="[e-mail]" url="http://e107.org" />
	<summary>Bootstrap3 e107 theme</summary>
	<description>a simple bootstrap 3 template for the frontend</description>
	<category>generic</category>
	<plugins>
		<plugin name='featurebox' url='core' />
		<plugin name='gallery' url='core' />
        <plugin name='rss_menu' url='core' />
        <plugin name='tinymce4' url='core' />
		<plugin name='social' url='core' />
	</plugins>
	<keywords>
		<word>bootstrap</word>
		<word>clean</word>
	</keywords>
	<screenshots>
		<image>preview_frontend.png</image>
	</screenshots>
	<libraries>
		<library name="bootstrap" version="3" scope="front,admin,wysiwyg"/>
		<library name="fontawesome" version="5"  scope="front,admin,wysiwyg"/>
		<library name="bootstrap.editable" scope="admin"/>
	</libraries>
	<stylesheets>
		<css file="style.css" name="Default" scope="front" />
		<css file="css/modern-light.css" name="Modern Light" description="A high-contrast light skin" thumbnail='images/admin_modern-light.webp' scope='admin' exclude='bootstrap'/>
	</stylesheets>
	<layouts>
		<layout name='jumbotron_home' title='Jumbotron (home)' default='false'>
			<custompages>FRONTPAGE</custompages>	
		</layout>
		<layout name='modern_business_home' title='Modern Business: Home page carousel with fixed custom-menus' />
		<layout name='jumbotron_full' title='Jumbotron (full-width)'  >
      <custompages>forum</custompages>
		</layout>
		<layout name='jumbotron_sidebar_right' title='Jumbotron (sidebar-right)' default='true' >
			<custompages>/news</custompages>
			<menuPresets>
				<area id='1'>
					<menu name='search' />
					<menu name='news_categories' />
					<menu name='other_news' />
					<menu name='other_news2' />
					<menu name='blogcalendar' />
				</area>
			</menuPresets>	
		</layout>
	</layouts>
	<themePrefs>
		<pref name='branding'>sitename</pref>
		<pref name='nav_alignment'>right</pref>
		<pref name='usernav_placement'>top</pref>
	</themePrefs>
</e107Theme>

Example #2: Minimal theme.xml

TODO: Provide minimal required theme.xml example

e107Theme

This is the namespace the configuration lives in. All theme.xml files must begin and end with this tag.

<e107Theme name="" version="3.0" date="2012-01-07" compatibility="2.0">
... all content belongs here ...
</e107Theme>

The following attributes of the theme are defined here:

Attribute	Description	Example	Mandatory?
name	The name of your theme. This can be text or a constant defined from your themes's language file.	Bootstrap3	Yes
version	The version of the theme (semantic versioning)	3.0	Yes
date	The date when the theme was released (latest version). (yyyy-mm-dd)	2020-30-12	Yes
compatibility	The minimum version of e107 required to use the theme. (semantic versioning)	2.1.0	Yes
price	In case of a commercial theme: the sales price of the theme. (xx.xx format)	25	No
currency	In case of a commercial theme: the abbreviation of the currency in which the theme is sold for (see price).	EUR	No
url	In case of a commercial theme: the direct URL to the specific theme. When the user clicks to download your theme, the URL you have provided will be loaded. ❗Note: do not add the URL to the generic homepage of your website, but only the URL to the specific page for that specific theme.	https://direct-path-to-purchase-page.com	No

👍 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". Just package the theme's zip file with only the theme.xml and any images (including screenshots), excluding .php, .css files etc. before sharing it in the 👉 developers area on e107.org. When the user clicks to download the theme, it will display the URL you have provided.

In previous versions of e107, the attribute releaseUrl was used. This attribute is deprecated and should be removed.

Author

Identifies the theme author and highlights some information.

<author name="e107 Inc" email="[e-mail]" url="https//e107.org" />

👍 Note the / to close the tag at the end.

The following attributes of the author are defined here:

Attribute	Description	Example	Mandatory?
name	The author's name, e107 user name or nickname.	e107 Inc.	Yes
email	E-mail address. Useful to get feedback and bug reports on the theme. A mailto link to it is displayed on the Admin Area > Theme Manager page.	[e-mail]	Yes
url	A link to the author's website. A link to it is displayed on the Admin Area > Theme Manager page.	https://www.e107.org	Yes
description	A brief description of your theme. Displayed on the Admin Area > Theme Manager page.	Example description of your choice.	No

Summary

A text that shortly summarises the theme.

<summary>Bootstrap3 e107 theme</summary>

TODO: Check if using LAN is possible

Description

A text that provides a more elaborate description of the theme.

<description>a simple bootstrap 3 template for the frontend</description>

TODO: Check if using LAN is possible.

Category

<category>generic</category>

The category that a theme belongs to. Possible values are:

• Generic

• Adult

• Blog

• Corporate

• Gaming

• News

Plugins

In this section, theme designers can include plugins that they intend to be used with the theme. In the 👉 "Theme Manager" > Site Theme > "Suggested Plugin" section with buttons for those plugins that the user can click on to install them.

<plugins>
    ...
</plugins>

plugin

<plugins>
		<plugin name='featurebox' url='core' />
</plugins>

Attribute	Description	Example	Mandatory?
name	Refers to the plugin folder name of the recommended plugin.	featurebox	Yes
url	For plugins that are included in e107 by default, use "core". For third-party plugins ....	core	Yes

TODO: check format for third-party plugins.

Keywords

The keywords associated with the theme. They are used when searching for plugins either through the Admin Area or on 👉 https://www.e107.org/themes.

<keywords>
		...
</keywords>

word

	<keywords>
		<word>bootstrap</word>
	</keywords>

Screenshots

Each theme can contain one or more screenshots. These screenshots are displayed in the Admin Area and on 👉 https://www.e107.org/themes.

	<screenshots>
		...
	</screenshots>

image

Refers to the location of the image file, relative to the root of the theme folder

	<screenshots>
		<image>preview_frontend.png</image>
	</screenshots>

Libraries

TODO: provide explanation

<libraries>
		<library name="bootstrap" version="3" scope="front,admin,wysiwyg"/>
		<library name="fontawesome" version="5"  scope="front,admin,wysiwyg"/>
		<library name="bootstrap.editable" scope="admin"/>
</libraries>

library

<libraries>
		<library name="fontawesome" version="5"  scope="front,admin,wysiwyg"/>
</libraries>

Attribute	Description	Example	Mandatory?
name	Name of the library	bootstrap.editable	Yes
version	Version of the library. (semantic versioning)	3	No
scope	The area in which the library is included. Possible values: front admin wysiwyg Can be multiple if separated by comma	admin	Yes

Stylesheets

	<stylesheets>
		...
	</stylesheets>

css

<css file="css/modern-light.css" name="Modern Light" description="A high-contrast light skin" thumbnail='images/admin_modern-light.webp' scope='admin' exclude='bootstrap'/>

Attribute	Description	Example	Mandatory?
file		css/modern-light.css	Yes
name		Modern Light	Yes
description		A high-contrast light skin	No
thumbnail		images/admin_modern-light.webp	No
scope		admin	Yes
exclude		bootstrap	No

TODO: asterix (*) usage?

Layouts

<layouts>
    ...
</layouts>

Each theme can contain various layouts. Additionally, each layout can be used for specific custom pages and each layout can have specific menu presets.

Layout

<layout name='modern_business_home' title='Modern Business: Home page carousel with fixed custom-menus' />

Attribute	Description	Example	Mandatory?
name	Shortname of the layout (use underscores)	jumbotron_home	Yes
title	Descriptive title of the layout	Home page carousel with fixed custom-menus	Yes
default	Indicates whether a layout is the default layout to be used. There can only be one default layout. Boolean - defaults to 'false'	true	No
preview	A preview image (thumbnail) of the layout. (recommended dimensions?)	preview.png	No
previewFull	A preview image of the layout (full size) (recommended dimensions?)	preview_full.png	No

Custom Pages

Each layout can assign specific pages which then, by default, make use of this specific layout. The user can modify the pages used by each layout in the 👉 "Theme Manager" > Site Theme > > Layouts section

<layouts>
		<layout name='jumbotron_home' title='Jumbotron (home)' default='false'>
			<custompages>FRONTPAGE</custompages>	
		</layout>
</layouts>

👍 You can use the constant FRONTPAGE to refer to the currently set 👉 frontpage setting.

Using the e_ROUTE constant

Adding $CUSTOMPAGES to theme.php in e107 v2.x is deprecated and should be avoided!

Menu Presets

Theme authors can create buttons for menus that can be activated by the user from "Menu Manager" or "Theme Manager". These are placed between and and should be enclosed in the and tags with the opening area tag naming the menu area it corresponds to; the example below would be for a layout with two (2) menu areas ({MENU=1} = and {MENU=2} = ). The tag "menu name" must contain the name of a valid and installed menu.

ThemePrefs

Set default theme preferences?

TODO: also refer to theme_config.php

pref

name, (value)

theme_config.php

This file can be used to add information and user-selectable options to the theme's configuration page.

👍 If you want users to b e able to set specific theme preferences, use the theme_config.php file.

Example

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>
        ";
    }
}

Favicon

Automatically, e107 is looking for the favicon.ico file in the following locatons in this specific order:

1. inside the root of the theme folder (e107_themes/yourtheme)

2. inside the root of the e107 installation (/)

This way, theme authors can override the default favicon, and users can upload their own favicon to the theme folder.

👍 TIP: To insert more favicons, you can use the 👉 Meta Tags