Installation & configuration
Please note: This page is under construction and has not been finished yet.
TODO:
- overview of install & config files (theme.xml & theme_config.php)
- highlight some options
- refer to example themes (bootstrap3)
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.
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="[email protected]" 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>
TODO: Provide minimal required theme.xml example
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. ❗ | No |
👍
👉
In previous versions of e107, the attribute
releaseUrl was used. This attribute is deprecated and should be removed. Identifies the theme author and highlights some information.
<author name="e107 Inc" email="[email protected]" 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. | Yes | |
url | https://www.e107.org | Yes | |
description | Example description of your choice. | No |
A text that shortly summarises the theme.
<summary>Bootstrap3 e107 theme</summary>
TODO: Check if using LAN is possible
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>generic</category>
The category that a theme belongs to. Possible values are:
- Generic
- Adult
- Blog
- Corporate
- Gaming
- News
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>
<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.
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>
<keywords>
<word>bootstrap</word>
</keywords>
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>
Refers to the location of the image file, relative to the root of the theme folder
<screenshots>
<image>preview_frontend.png</image>
</screenshots>
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>
<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:
Can be multiple if separated by comma | admin | Yes |
<stylesheets>
...
</stylesheets>
<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>
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 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 |
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>
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.
Set default theme preferences?
name, (value)
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.
👍
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>
";
}
}
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.
Last modified 2mo ago