# Installation & configuration

{% hint style="danger" %}
**Please note:** This page is under construction and has not been finished yet.
{% endhint %}

## Introduction

{% hint style="info" %}
TODO:

* overview of install & config files (theme.xml & theme\_config.php)
* highlight some options
* refer to example themes (bootstrap3)
  {% endhint %}

## theme.xml

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

{% hint style="success" %}
:thumbsup: **TIP:** To create a new `theme.xml` file or derive one from an existing v1.x `theme.php` file use the [conversion tool](https://userguide.e107.org/administration/manage/theme-manager#tools) in the Admin Area > Theme Manager > Tools \
(`/e107_admin/theme.php?mode=convert`)
{% endhint %}

{% hint style="info" %}
**Please note:** Unlike [plugin.xml](https://devguide.e107.org/plugin-development/installation-and-configuration#plugin-xml), the theme.xml file is not intended to replace the [theme.php](https://devguide.e107.org/layout-and-templates#theme-php) file. Instead, theme.xml works alongside [theme.php](https://devguide.e107.org/layout-and-templates#theme-php) to provide (meta)data about the theme itself.
{% endhint %}

### 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. 

```markup
<?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="e107inc@something.com" 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

{% hint style="info" %}
TODO: Provide minimal required theme.xml example
{% endhint %}

### e107Theme

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

```markup
<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**       | <p>The version of the theme</p><p>(semantic versioning)</p>                                                                                                                                                                                                                                                                                                                                                    | 3.0                                                                                          | **Yes**    |
| **date**          | The date when the theme was released (latest version). (yyyy-mm-dd)                                                                                                                                                                                                                                                                                                                                            | 2020-30-12                                                                                   | **Yes**    |
| **compatibility** | <p>The minimum version of e107 required to use the theme.</p><p>(semantic versioning)</p>                                                                                                                                                                                                                                                                                                                      | 2.1.0                                                                                        | **Yes**    |
| price             | <p>In case of a commercial theme: the sales price of the theme. </p><p>(xx.xx format)</p>                                                                                                                                                                                                                                                                                                                      | 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               | <p>In case of a commercial theme: the direct URL to the specific theme. </p><p></p><p>When the user clicks to download your theme, the URL you have provided will be loaded. </p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="2757">❗</span><em>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.</em></p> | [https://direct-path-to-purchase-page.com](http://direct-path-to-my-theme-purchase-page.com) | No         |

{% hint style="success" %}
&#x20;:thumbsup: **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](https://userguide.e107.org/administration/manage/theme-manager#find-themes)". \
\
Just package the theme's zip file with only the [theme.xml](#theme-xml) and any images (including screenshots), excluding .php, .css files etc. before sharing it in the :point\_right: [developers area on e107.org](https://e107.org/developers).\
\
When the user clicks to download the theme, it will display the **URL** you have provided.
{% endhint %}

{% hint style="info" %}
In previous versions of e107, the attribute `releaseUrl` was used. This attribute is deprecated and should be removed.&#x20;
{% endhint %}

### Author

Identifies the theme author and highlights some information. &#x20;

```markup
<author name="e107 Inc" email="e107inc@something.com" url="https//e107.org" />
```

:thumbsup: *Note the `/` to close the tag at the end.*&#x20;

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*](https://userguide.e107.org/administration/manage/theme-manager) page. | <e107inc@something.com>             | **Yes**    |
| url         | A link to the author's website. A link to it is displayed on the *Admin Area >* [*Theme Manager*](https://userguide.e107.org/administration/manage/theme-manager) page.                                               | <https://www.e107.org>              | Yes        |
| description | A brief description of your theme. Displayed on the *Admin Area >* [*Theme Manager*](https://userguide.e107.org/administration/manage/theme-manager) page.                                                            | Example description of your choice. | No         |

### Summary

A text that shortly summarises the theme.&#x20;

```markup
<summary>Bootstrap3 e107 theme</summary>
```

{% hint style="info" %}
TODO: Check if using LAN is possible
{% endhint %}

### Description

A text that provides a more elaborate description of the theme.&#x20;

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

{% hint style="info" %}
TODO: Check if using LAN is possible.&#x20;
{% endhint %}

### Category

```markup
<category>generic</category>
```

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

* Generic&#x20;
* Adult&#x20;
* Blog&#x20;
* Corporate&#x20;
* Gaming&#x20;
* News

### Plugins

In this section, theme designers can include plugins that they intend to be used with the theme. In the :point\_right: "[Theme Manager](https://userguide.e107.org/administration/manage/theme-manager)" > [Site Theme](https://userguide.e107.org/administration/manage/theme-manager#site-theme) >  "[Suggested Plugin](https://userguide.e107.org/administration/manage/theme-manager#suggested-plugins)" section with buttons for those plugins that the user can click on to install them.&#x20;

```markup
<plugins>
    ...
</plugins>
```

#### plugin

```markup
<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**   | <p>For plugins that are included in e107 by default, use "core". </p><p>For third-party plugins .... </p> | core       | **Yes**    |

{% hint style="info" %}
TODO: check format for third-party plugins.&#x20;
{% endhint %}

### Keywords

The keywords associated with the theme. They are used when searching for plugins either through the Admin Area or on :point\_right: <https://www.e107.org/themes>.&#x20;

```markup
<keywords>
		...
</keywords>
```

#### word

```markup
	<keywords>
		<word>bootstrap</word>
	</keywords>
```

### Screenshots

Each theme can contain one or more screenshots. These screenshots are displayed in the Admin Area and on :point\_right: <https://www.e107.org/themes>.&#x20;

```markup
	<screenshots>
		...
	</screenshots>
```

#### image

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

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

### Libraries

{% hint style="info" %}
TODO: provide explanation
{% endhint %}

```markup
<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

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

| **A**ttribute | Description                                                                                                                                                                | Example            | Mandatory? |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------- |
| **name**      | Name of the library                                                                                                                                                        | bootstrap.editable | **Yes**    |
| version       | <p>Version of the library. <br>(semantic versioning)</p>                                                                                                                   | 3                  | No         |
| **scope**     | <p>The area in which the library is included.<br><br>Possible values:</p><ul><li>front</li><li>admin</li><li>wysiwyg</li></ul><p>Can be multiple if separated by comma</p> | admin              | **Yes**    |

### Stylesheets

```markup
	<stylesheets>
		...
	</stylesheets>
```

#### css

```markup
<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'/>
```

| **A**ttribute | 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         |

{% hint style="info" %}
TODO: asterix (\*) usage?
{% endhint %}

### Layouts

```markup
<layouts>
    ...
</layouts>
```

Each theme can contain various layouts. Additionally, each layout can be used for specific[ custom pages](#custom-pages) and each layout can have specific [menu presets](#menu-presets).

#### Layout

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

| Attribute   | Description                                                                                                                                             | Example                                    | Mandatory? |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------- |
| **name**    | <p>Shortname of the layout</p><p>(use underscores)</p>                                                                                                  | jumbotron\_home                            | **Yes**    |
| **title**   | Descriptive title of the layout                                                                                                                         | Home page carousel with fixed custom-menus | **Yes**    |
| default     | <p>Indicates whether a layout is the default layout to be used. There can only be one default layout. </p><p><em>Boolean - defaults to 'false'</em></p> | true                                       | No         |
| preview     | <p>A preview image (thumbnail) of the layout. </p><p>(recommended dimensions?)</p>                                                                      | preview\.png                               | No         |
| previewFull | <p>A preview image of the layout (full size)</p><p>(recommended dimensions?)</p>                                                                        | 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 :point\_right: "[Theme Manager](https://userguide.e107.org/administration/manage/theme-manager)" > [Site Theme](https://userguide.e107.org/administration/manage/theme-manager#site-theme) >  > [Layouts section](https://userguide.e107.org/administration/manage/theme-manager#layouts)

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

{% hint style="success" %}
:thumbsup: You can use the constant `FRONTPAGE` to refer to the currently set :point\_right: [frontpage](https://userguide.e107.org/administration/settings/front-page) setting.&#x20;
{% endhint %}

[Using the e\_ROUTE](https://devguide.e107.org/classes-and-methods/urls#using-e_route) constant

{% hint style="warning" %}
Adding `$CUSTOMPAGES` to [theme.php](https://devguide.e107.org/layout-and-templates#theme-php) in e107 v2.x is deprecated and should be avoided!
{% endhint %}

#### 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](#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.&#x20;

{% hint style="success" %}
:thumbsup: If you want users to b e able to set specific theme preferences, use the theme\_config.php file.&#x20;
{% endhint %}

#### Example

```php
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**:&#x20;

1. inside the root of the theme folder (`e107_themes/yourtheme`)&#x20;
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.&#x20;

{% hint style="success" %}
:thumbsup: **TIP:** To insert more favicons, you can use the :point\_right: [Meta Tags](https://userguide.e107.org/administration/settings/meta-tags)
{% endhint %}