Knowledge Base / Category / Theme basics

Theme basics

(this tutorial is based on old tutorial for v 0.7.6 by Aldrin from www.etalkers.org as a way of my thanks )

Be aware. To understand this tutorial you need at least to have basic knowledge of HTML/PHP.

Definitions

Basic terms

1.1. Theme

We call the THEME (for) all elements related to the graphical layout of your site: pictures, fonts, colours... All files related to the theme are saved in a unique folder.

1.2. Css

CSS (cascading style sheet) is used for all elements related to the style of your SITE. A font is a style, colour is a style, a font-size is a style... etc... A style is created using one (or more) file(-s) with .css as EXTENSION.

1.3. Bootstrap based theme

e107 is by default based on the Bootstrap framework, so Jquery library is loaded by default too. The term bootstrap based theme means that bootstrap is loaded into the theme on the frontend. The Admin area always uses the bootstrap3 theme. How to create a theme without jquery is not part of this tutorial. You can, of course, create a theme without bootstrap.

1.4. Header

In e107, the header is the part of your page BEFORE the main content (it can be on the top or/and the left part of the page). By default, the header is the same for ALL pages on site.  Now is header part of the layout HTML file. It starts with <body tag.

1.5. Footer

in e107 the footer is part AFTER main content. By default, the footer is the same for ALL pages on site. Now is footer part of the layout HTML file. No closing body tag is needed.

1.6. Menus

Menus or menu areas are places where the content of menus/blocks is displayed. Each layout has its own set of menu areas. In the code you can find it as .  For homepage is the content of Frontpage page (it's can be different for userclasses), otherwise content of desired page is displayed.  

Content should be rendered via tablerender() method and it has always 2 parts - caption and text. How those parts are displayed depends on used style in tablestyle() method. 

Related topics:

  • frontpage
  • welcome message 
  • tablestyle()
  • tablerender()

1.8. Templates

 The way how to add HTML markup to e107 shortcodes before the content is rendered. 

1.9. Layouts

new in 2.2.2

Html files to display different page layout for different page. What layout is used depends on theme settings. 

Before the global array $LAYOUT was used.  

Theme Folder Structure

Folder "e107_themes/your_theme"

Each theme is saved in a unique subfolder inside/as part of your e107_themes folder. The theme folder is called with a theme name. This name will be used through your site. If you plan to share your theme via https://e107.org/, be sure to use the unique name for your theme.
updated for version 2.2.2

Structure

Required files and folders:

  • theme.xml
  • theme.php
  • style.css
  • theme.html
  • layouts folder

Optional files and folders:

  • style_custom.css
  • theme_config.php
  • theme_library.php
  • install folder
  • image / assets folder
  • custom.js

File theme.xml

what elements in theme.xml mean

updated for version 2.2.2

See the new Bootstrap 4 theme.

Version 2 Description
<e107Theme name="Bootstrap 4" define the theme name
<e107Theme version="1.0" define the theme name
<e107Theme date="2018-06-24" define the theme date
<e107Theme compatibility="2.2.1" define the theme compatibility
<e107Theme livedemo='http://e107.org' Link to live demo
<author name ="e107" define the theme author
<author email="..." define email contact to the theme author
<author url="..." define the theme author website
<category></category>

Сategory used on e107.org. Allowed categories: generic, adult, blog, clan, children, corporate, forum, 

gaming, gallery, news, social, video, multimedia.

<plugins></plugins> List of plugins you can install directly from Theme manager. System checks if they are installed or not. If your theme needs some core or non-core plugins.
<stylesheets></stylesheets> If your theme has more css for color settings (with boostrap it’s easy), you can switch between them in theme manager
<layouts></layouts> Available layouts that you can define layout html files inside layouts folder. You can set pages with this layout, default layout and menus for this layout (you can set them in Menu manager too)
<libraries></libraries> The prefered way how to use libraries in theme now. Defining of bootstrap and font awesome constants is not recommended.
<glyphicons></glyphicons> Load different icon set in theme
<themePrefs></themePrefs> Default values for theme prefs. Theme prefs are defined in theme_config.php file.

File theme.php

Information you can find in theme.php

Basic description of file theme.php to understand when you open it and you are trying to change something.
Updated for version 2.2.2

Constants

No constants should be used in theme.php now. 

define("BOOTSTRAP", 3);

define("FONTAWESOME", 4);

should be replaced in theme.xml file by:

bootstrap 3:

<libraries>
<library name="bootstrap" scope="all"/>
<library name="fontawesome" scope="all"/>
</libraries>

bootstrap 4:

<libraries>
<library name="bootstrap" version="4" scope="all"/>
<library name="fontawesome" version="5" scope="all"/>
</libraries>

define('BODYTAG', '<body class="body-class '.THEME_LAYOUT.'">');

should by in theme.html replaced by

<body id="page-top" class="{LAYOUT_ID}" {BODY_ONLOAD} >

 


define('VIEWPORT', "width=device-width, initial-scale=1.0");

should be replaced in theme.php

e107::meta('viewport', 'width=device-width, initial-scale=1.0');

it is used for meta tag viewport in header_template.php (proper rendering and touch zooming if applicable)

No legacy stuff should be used in themes for version 2.2.2

 

There are still constants used in code from version 1 (I just let them there because default theme use them too):

define('OTHERNEWS_COLS',false); // no tables, only divs.

define('OTHERNEWS_LIMIT', 3); // Limit to 3.

define('OTHERNEWS2_COLS',false); // no tables, only divs.

define('OTHERNEWS2_LIMIT', 3); // Limit to 3.

define('COMMENTLINK', e107::getParser()->toGlyph('fa-comment'));

define('COMMENTOFFSTRING', '');

define('PRE_EXTENDEDSTRING', '<br />');

Update 2017/09: COMMENTLINK has default value in core, so no need to use it in theme.php, only if you want to have your own. Example of constants you can find in old themes:

Constant Description
define("STANDARDS_MODE", TRUE); Mainly IE ; correct boxmodel (legacy)
define("IMODE", "lite"); Icon-set use (eg forum dark/lite (legacy)
define("THEME_DISCLAIMER", "<br /><i>".LAN_THEME_1."</i>"); theme disclaimer (themeinfo)
define('WMFLAG', ''); Welcome message is not displayed at all, use {WMESSAGE=hide} now

Libraries

load core libraries directly in theme.php is not needed anymore, theme.xml is enough

e107::library('load', 'bootstrap');

e107::library('load', 'fontawesome');

Where are core libraries files located?

You can find all information in Settings/Libraries.  

What paths are used depends if you use them locally or not.  

D410654fddcf

Note: from version 2.2.2 libraries should (could) be defined in theme.xml file, what is prefered way.  It doesn't mean you can't load them manually from theme folder without libraries at all.

Load theme css and js files

For detailed information see Developer Manual Examples related to theming:

IE fix example:

e107::js('url','https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js','','2','<!--[if lt IE 9]>','');
e107::js('url','https://oss.maxcdn.com/respond/1.4.2/respond.min.js','','2','','<![endif]-->');

Activate bootstrap tooltips :

e107::js("footer-inline", "$('.e-tip').tooltip({container: 'body'})");

Load scripts after JQuery:

e107::js("theme", "js/scripts.js", 'jquery');

Load translated strings

e107::lan('theme');

For Frontend your language strings should be a file with name English.php (or your language). For Admin part there should be an English_admin.php file (or your language). Both reside in languages folder inside your theme.

How to change emoticons size

Emoticons in version 2 are smaller than in version 1

Css example for changing emoticons size
Create file style_custom.css in your theme folder if not exists (to avoid problems with update)
and add this code:

/* FIX for emoticon size */
img.e-emoticon {
width: 60px;
}

You can insert it directly in style.css if you know what you are doing.

File theme.html

The easiest way how to set theme layout

LAYOUT

This file has to have this one magic shortcode to let e107 engine know where to output page content (it depends on layout settings)

<!-- Page Content -->
{---LAYOUT---}


Everything above this code is considered as default header and everything bellow this shortcode is considered as default footer.  

Content of LAYOUT shortcode is defined in HTML layout files. 

This replaces:

$LAYOUT['_header_']
$LAYOUT['_footer_']


and they are not needed anymore.

Using different headers is considered as the advanced topic and it's not officially supported. But it's easier now than before. With JM Theme plugin it's possible via admin area. 

HEADER

The header is part of this file.  It starts with body tag, so global BODYTAG is not needed anymore. It ends before {---LAYOUT---}.

Example for bootstrap3 theme (the same code as in theme.php):

<body id="page-top" class="{LAYOUT_ID}" {BODY_ONLOAD} >
{---MODAL---}
<div class="navbar navbar-inverse navbar-fixed-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="{SITEURL}">{BOOTSTRAP_BRANDING}</a>
</div>
<div class="navbar-collapse collapse {BOOTSTRAP_NAV_ALIGN}">
{NAVIGATION=main}
{BOOTSTRAP_USERNAV: placement=top}
</div><!--/.navbar-collapse -->
</div>
</div>

FOOTER

Footer is part of this file. It starts after {---LAYOUT---} . No closing body tag is needed.

Example of theme.html :

<body id="page-top" class="{LAYOUT_ID}" {BODY_ONLOAD} >

{---MODAL---}
<!-- Header -->
<nav class="navbar navbar-expand-lg navbar-dark bg-dark fixed-top">
<div class="container">
<a class="navbar-brand" href="{SITEURL}">{SITENAME}</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarResponsive" aria-controls="navbarResponsive" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="collapse navbar-collapse" id="navbarResponsive">
{NAVIGATION=main}
</div>
</div>
</nav>


<!-- Page Content -->
{---LAYOUT---}

<!-- Footer --> 
{SETSTYLE=footer} 
<footer class="footer py-4 bg-dark text-white"> 
<div class="container"> 
<div class="content"> 
<div class="row"> 
<div class="col-md-3"> <h4>Navigation</h4>{NAVIGATION: type=main&layout=alt} 
</div> 
<div class="col-md-3"> <h4>Follow Us</h4>{XURL_ICONS: template=footer} 
</div> 
<div class="col-md-3"> {MENU=105} 
</div> 
<div class="col-md-3"> {MENU=106}
</div> 
</div> 
</div> 
<hr> 
<div class="container"> {NAVIGATION: type=main&layout=footer} </div>
<div class="container"> 
<p class="m-0 text-center text-white">{SITEDISCLAIMER}</p>
</div> 
<!-- /.container -->
</div>
</footer>

<!-- Javascripts and other information are automatically added below here -->
</body> <!-- This tag is not necessary and is ignored and replaced. Left here only as a reference -->

Used shortcodes:

  •   core shortcode for actual layout (the same as THEME_LAYOUT)
  • core shortcode for inserting specific code when page is loaded, see header_template.php in core/templates folder
  •  

Layouts

Languages

If you use custom text in your theme, you should use LANs constants.

For frontend:  English.php

For admin:  English_admin.php

Using:

Frontend:  e107::lan('theme');

Admin: e107::themeLan('admin','bootstrap4', true);

Already used LANs for theme prefs in bootstrap 4 theme (example):

LAN_THEMEPREF_01 Inline CSS <br> between head tags
LAN_THEMEPREF_02 Inline JS <br> after body tag
LAN_THEMEPREF_03 Iframe code for google maps on Contact Page
LAN_THEMEPREF_04 Display standard menu with card look

Magic shortcodes

 New e107 2.2.2

Magic shortcode Meaning Supported (tested) Note
{---CAPTION---}
Page title Forum, Downloads, News, Gallery, GSitemap, Vstore

contact

Only for STYLE default or main
{---BREADCRUMB---}
Actual breadcrumbs 

Forum, Downloads, News, Gallery, GSitemap, Vstore

contact

{---TEXT---}
Subtitle
{---LAYOUT---}
Layout content in theme.html
{---MODAL---}
Modal window in theme.html   header   footer for your own $LAYOUT['_modal_'] in theme.php
{---HEADER---}
Custom Header in theme.html  header   footer defined in theme shortcodes sc_header()
{---FOOTER---}
Custom Footer in theme.html   header   footer defined in theme shortcodes sc_footer()
{THEME}
Themes folder path (THEME_ABS)

theme.html, *_layouts.html  header   footer

for use in a hardcoded path to images in HTML files
{BODY_ONLOAD}
for body tag in theme.html  header old  $body_onload (default) is used only with this, without it, body tag is clean (for you to use anything)
{LAYOUT_ID}
unique layout text ID (layout-xxx)  in theme.html  header mainly for the body tag