Welcome to the new Developer Guide for e107.

The Developer Guide is still under construction but more and more information is added over time.

You can use the menu on the left to navigate to the underlying pages.

To create a simple test script, create a new file called helloworld.php in your root folder with the following PHP code:

<?php

require_once("class2.php"); // Load e107's main classes and functionalities
require_once(HEADERF); // Load and output the theme's HTML for the $HEADER.

// Option 1:
echo "Hello World";

// Option 2:
$ns = e107::getRender(); // Load rendering object. 
$ns->tablerender("My Caption", "Hello World");  // Render Caption and Text according to Theme style. 

require_once(FOOTERF); // Load and output the theme's HTML for the $FOOTER. 
exit; 

Then point your browser to www.yoursite.com/helloworld.phpand you're ready!

The table below provides an overview of the default folder structure of an e107 installation:

Introduction

Use the following to retrieve the alerts class object.

Alerts methods

addSuccess()

addError()

addWarning()

addInfo()

addDebug()

render()

None of the above methods will output anything, until you use this method to render them.

• You can redirect to a URL using the following static method:

Introduction

Returns an array of user data for a specific user. Input can be either a specific ID ($user_id) or use USERID for the currently logged in user.

Introduction

Use the following to retrieve the language class object

myplugin_shortcodes.php

Theme shortcodes

Plugin shortcodes

Introduction

Use the following to retrieve the render class object.

$ns = e107::getRender();

Render methods

tablerender()

Send HTML to the browser for output.

Introduction

You can log events to the admin System Logs by using the built in log class. Use the following to retrieve the alerts class object.

Logging methods

add()

Logging types

Introduction

Use the following to retrieve the render class object.

$pref = e107::getPref();

Retrieving preferences

Developers may retrieve admin preferences for their theme or plugin, or a core preference using the following method:

Example: Load a stored value that was saved in the preferences admin area of the 'faqs' plugin

Or load a single preference value.

Plugins extended the functionality of e107 and allow for endless possibilities.

CORE/THIRD PARTY - LINK TO USER GUIDE

ARCHITECTURE

The plugin architecture is developed to be as simple as possible. Often you can copy a file from an existing plugin and simply modify a few parameters in order to get similar functionality in your own plugin

Folder structure

Example: blank plugin

• images

  • sizes?

• languages

Required files

• plugin.xml

Optional files

• admin_config.php

• *_setup.php

• *_sql.php

• e_*.php addons

Introduction

• 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 and for snippets: .

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

style.css

Include meta tags in the html header.

e107::meta($name, $content, $extended);

Examples

Introduction

Introduction

...

Introduction

Introduction

......

Overview

The table below provides a quick overview of all classes that are used in e107 and are commonly used by developers.

Introduction

Cache methods

retrieve()

retrieve_sys()

set()

clear()

clear_sys()

Cache types

Introduction

Themes developed for v1.x of e107 will continue to work using v2.x. However, to get the most out of v2.x, it is recommended to make the following changes to bring your theme up to date with the new v2.x standards.

theme.php

• Replace $HEADER and $FOOTER with $HEADER['default'] and $FOOTER['default']

• Replace any occurrences of $CUSTOMHEADER and $CUSTOMFOOTER with $HEADER['custom'] and $FOOTER['custom']

• If your theme contains links to external social media pages such as Facebook, Twitter or YouTube, use the core definitions for them. ie. XURL_FACEBOOK, XURL_TWITTER,

• 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 or 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 file. ($register[]

Theme shortcodes

Read more on theme shortcodes here:

Introduction

By far, the quickest and easiest way to develop a plugin for e107 is to use the Plugin Builder, because:

• It allows you to select the database file () file from the plugin folder, or directly from the database table list, and it will generate most of the new code for the of your plugin.

• It will generate the new meta-file, which is used during installation of your plugin and also when sharing plugins via this site.

How to use the Plugin Builder

1. Create an empty plugin folder in e107_plugins (eg. "myplugin")

2. Create a new text file with the *_sql.php extension. (eg. "myplugin_sql.php")

3. Using a tool such as phpMyAdmin, create your database table structure, and then export it in SQL format.

Basic info

Database tables

field

caption

type

data

width

batch

filter

inline

validate

display

R/O

Helptip

ReadParms

WriteParms

Preferences

Addons

Introduction

Your code should not produce any PHP warnings or notices during normal usage. This primarily implies that all variables must be defined before being used. It also implies that a corrupted installation may produce errors, although as far as practicable the code should accommodate this.

Introduction

You can generate a Search Engine Friendly (SEF) URLs using the following method:

Introduction

Date methods

computeLapse()

Calculate difference between two dates for display in terms of years/months/weeks....

convert_date()

Convert datestamp to human readable date. System time offset is considered.

terms()

Return an array of language terms representing months

Introduction

Your website can be used in different languages. In order for your plugin or theme areas to be displayed in a specific language, it needs to be translated.

Language files

File Types

There are three types of language files that can be used in your plugin.

Defining Language Terms

Language Terms are more commonly known as LAN's. You can define LAN's by using PHP constants:

Best practices

👍 Always use the format LAN_PLUGIN_{FOLDER}_{TYPE} to prevent conflicts.

Avoid duplicating terms, particularly in the admin area.

👍 If defining terms for admin, always search lan_admin.php for existing LANs which may match what you require.

Never use HTML or URLs inside LAN definitions.

👍 Use double quotes within the defines and use str_replace() or 👉 for where needed.

Avoid short language strings for common words

Examples are words such as 'and', 'to' and so on. There aren't always equivalents in other languages.

👍 If embedding values into a phrase, use .

Avoid using terms which are real words or known BBCodes.

👍 Use brackets [..] and values such as x, y, z. See below.

Examples

Good

Bad

Substitution

Loading Language Files

e107::lan()

To load a language file from a plugin folder, use e107::lan():

This will include the following paths:

Introduction

• Templates and shortcodes function together to allow a developer to place dynamic content into their code.

• Templates are portions of HTML which contain markers that are replaced by dynamic content when parsed e107's parseTemplate()function.

• These markers are called 'shortcodes'.

• A shortcode is always CAPITALIZED and is surrounded by curly brackets and it may contain letters and underscores. For example: {MY_SHORTCODE}

• Each shortcode has a corresponding function/method which is run during the parsing of the template. These functions are always lowercase and begin with the prefix sc_ . eg. sc_my_shortcode(). This means that {MY_SHORTCODE} is replaced by what is returned by sc_my_shortcode().

• Shortcodes may also contain parameters which are sent to the corresponding method. For example: {MY_SHORTCODE: x=foo&y=bar}

Creating templates

Create a folder called templates inside your plugin directory, and inside create an empty file using the name of your plugin folder, followed by _template.php. eg. myplugin_template.php Inside this file add an array by the same name, but in UPPERCASE: eg. $MYPLUGIN_TEMPLATE['xxxx'] xxxx can be anything you want, but we suggest using start, item, end etc. when applicable. This value should always be lowercase. Here's a simple example of the contents of myplugin_template.php:

If your plugin will use several different types of templates, eg. a listing page and an input form. You can do something like this:

Loading templates

You may load a template file in the following way:

You can now use the $template code array for parsing:

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.

Examples

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.

Introduction

....

Basic Javascript methods

Including Javascript in your plugin or theme may be achieved by using the following function:

type & data

Examples

Example #1

Load a script in the 'faqs' plugin directory and auto-load jQuery if not already loaded.

Example #2

Load a theme script in the footer

Example #3

Load a theme script in the header

settings

An associative array with configuration options.

• The array is merged directly into e107.settings.

• All plugins should wrap their actual configuration settings in another variable to prevent conflicts in the e107.settings namespace.

• Items added with a string key will replace existing settings with that key; items with numeric array keys will be added to the existing settings array.

JavaScript Behaviors

Behaviors are event-triggered actions that attach to page elements, enhancing default non-JavaScript UI's.

Behaviors are registered in the e107.behaviors object using the method 'attach' and optionally also 'detach' as follows:

e107.attachBehaviors is added to the jQuery ready event and so runs on initial page load. Developers implementing Ajax in their solutions should also call this function after new page content has been loaded, feeding in an element to be processed, in order to attach all behaviors to the new content.

See the e107_web/js/core/all.jquery.js file for more information.

Using jQuery

jQuery is now namespaced to avoid conflicts with other Javascript libraries such as Prototype. All your code that expects to use jQuery as $ should be wrapped in an outer context like so.

If you don't, you may see the following error:Uncaught TypeError: Property '$' of object [object DOMWindow] is not a function or similar

jQuery Once

e107.behaviors will often be called multiple times on a page. For example, core/custom plugin performs some Ajax operation, all e107 behaviors will be executed again after page load, in order to attach any relevant JavaScript to the newly loaded elements.

This can have the undesired affect of applying JavaScript to elements each time e107 behaviors are executed, resulting in the same code being applied multiple times. To ensure that the JavaScript is applied only once, we can use the jQuery $.once() function. This function will ensure that the code inside the function is not executed if it has already been executed for the given element.

Using jQuery $.once() (integrated into e107 core), the developer experience of applying these effects is improved. Note that there is also the $.removeOnce() method that will only take effect on elements that have already applied the behaviors.

Settings passed locally to JavaScript Behaviors

How to override a JavaScript Behavior

If you want to override a bit of core (or third party) e107 JavaScript Behavior, just copy the behavior to your Javascript file (e.g in your plugin or theme), then load it after the original code using "zones".

Introduction

Back in September 2015, e107 v2.0.0 was officially released. Currently, any older version of e107 (such as version 1.0.4) is considered to be Legacy, and is also referred to as e107 v1.x.

Plugins and themes developed for e107 v1.x will continue to work on v2.x. However, to get the most out of v2.x, it is strongly recommended for developers to make changes to their code and bring the code up to the new v2.x standards.

This way, developers can:

• Ensure continued functionality of their plugins and themes in future versions of e107

• Benefit from major performance and security enhancements.

• Benefit from all new features and functionalities that are being developed in v2.x.

PHP and MySQL versions

The functionality of plugins also depends on the PHP and MySQL versions that are being used.

Plugins that are not regularly updated may make use of deprecated and/or removed PHP/MySQL functionality. In this case, plugins can cause a website to malfunction, or plugins appear to be broken.

Minimum and recommended changes

Minimum Changes:

• Include a file

Recommended Changes:

• Include a file

• Use e107's class for all form elements.

• Use 👉 in your templates and/or HTML markup

Classes & methods

In e107 v2.x, numerous classes and methods were introduced in order to standardize functionality across installations, ensure continued functionality and to minimize performance issues and security risks.

Frontend

HTML & CSS

e107 v2.x follows the for . Some examples:

• <input class='button' should become <input class='btn button'

• <table class='fborder' should become <table class='table fborder'

• <table>

Templates

Loading Templates

e107 v2.x uses a new template loading system.

Plugin templates should be stored in /yourplugin/templates/ by default. The template file should contain a variable with the same name as your template file. Instead of including the template, below is the difference:

..and then you can parse it the same way:

Declaring the HTML Template

eg. If your file is called myplugin_template.php , within this file you might see something like this:

Shortcode Wrappers.

In v2.x there are two methods to add wrappers around your shortcodes. The way to declare them differs slightly from v1 in that we use a kind of 'shortcode-wildcard' {---}.

Global Shortcodes

A global shortcode wrapper. ie for shortcodes which are available site-wide. (for example those registered globally for use in menus or found in e107_core/shortcodes/single/)

Example:

Template-Specific Shortcodes

v2.x introduces a template-specific shortcode wrapper. ie. as used on a single page of your site. Example:

Admin Area

In e107 v2.x, the Admin Area uses a special admin "handler", the .

In the Plugin Manager you will find something called "". It allows you to select your e107 file from your plugin folder and will generate most of the new code for the Admin Area of your plugin. It will also generate the new meta-file, which is used during of your plugin.

Migrating plugin preferences

migrateData()

To easily migrate from one to the other, one can use the method called migrateData().

Example of migrating plugin preferences to their own row in the database:

Introduction

Use the following to retrieve the database class object

Basic database methods

select()

Selecting data from a database table

Example #1: Simple select

Example #2: Using arguments

Example #3: Using arguments with noWhere option

Example #4: BIND support

fetch()

Selecting, looping through and displaying selected data with the fetch() method:

insert()

Inserting data into a database table:

update()

Updating information in a database:

retrieve()

Combined and method.

Example #1: Get a single value

Example #2: Get multiple table-row values

Example #3: Fetch all, don't append WHERE to the query, index by user_id, noWhere auto detected (string starts with upper case ORDER)

Example #4: Same as above but retrieve() is only used to fetch, not useable for single return value

Example #5: Using whole query example, in this case default mode is 'one'

Example #6: Using whole query example, multi mode - $fields argument mapped to $multi

delete()

Delete a record from a database table.

gen()

Generic query function to use various SQL commands.

Example: perform a JOIN with gen():

Advanced database methods

connect()

count()

database()

getLastErrorNumber()

getLastErrorText()

Introduction

Use the following to retrieve the form class object

Introduction

Use the following to retrieve the parser class object.

Theme shortcodes

Introduction

Plugin developers can hook into various e107 core events and trigger functions of their own. Typically, an e_event.php file is used to store this information since it is loaded with every page.

Events methods

register()

Example 1: trigger myFunction() on user login.

Example 2: trigger myFunction() on user login. Function in external file.

Example 3: trigger a class and method on user login.

trigger()

Triggers an event. This can be used by plugin authors to create their own plugin events that other developers can hook into.