Upgrading legacy plugins

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.

👍 Even though a lot of effort has been put in retaining backwards compatibility with older versions of e107, developers are strongly encouraged to update their code to new standards.

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.

TIP: When updating plugins, take into consideration the latest PHP/MySQL developments to ensure continued functionality.

Check the 👉 requirements page for more information on the minimal and recommended requirements for an e107 installation.

Minimum and recommended changes

Minimum Changes:

• Include a plugin.xml file

Recommended Changes:

• Include a plugin.xml file

• Use e107's Forms class for all form elements.

• Use 👉 Bootstrap HTML/CSS standards in your templates and/or HTML markup

• Upgrade e107 addons (e_xxxx.php files) to v2.x standards

• Upgrade language-files to new standards

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.

Developers are strongly encouraged to make use of e107's standard classes & methods

Introduction

TODO: Provide examples of legacy methods

Frontend

HTML & CSS

e107 v2.x follows the bootstrap standard for CSS. Some examples:

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

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

• <table> which use the class 'fcaption' on <td> should change the <td> to <th>.

• Using the forumheader3 class in the Admin Area is obsolete and can be removed.

Templates

👍 TIP: Read more about templates & shortcodes

Loading Templates

e107 v2.x uses a new template loading system.

Plugin templates should be stored in e107_plugins/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:

// e107 v1.x and older
require_once(e_PLUGIN."myplugin/templates/myplugin_template.php"); // v1.x

// from e107 v2.x onwards
$MYPLUGIN_TEMPLATE = e107::getTemplate('myplugin');

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

$text = $tp->parseTemplate($MYPLUGIN_TEMPLATE['start'], false, $my_shortcodes);

👍 TIP: Read more about the parsing methods

Declaring the HTML Template

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

$MYPLUGIN_TEMPLATE['start'] = "<div>";
$MYPLUGIN_TEMPLATE['end'] = "</div>";

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' {---}.

👍 TIP: Read more about shortcodes

Core ShortcodesShortcodes

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:

// v1.x way of doing it. 
$sc_style['CONTACT_PERSON']['pre'] = "<small>".LANCONTACT_14."</small><div>";
$sc_style['CONTACT_PERSON']['post'] = "</div>";

// v2.x way of doing it. 
$SC_WRAPPER['CONTACT_PERSON']= "<small>".LANCONTACT_14."</small><div>{---}</div>";

Template-Specific Shortcodes

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

$CONTACT_WRAPPER['form']['CONTACT_PERSON'] = "<small>".LANCONTACT_14."</small><div>{---}</div>";

Admin Area

In e107 v2.x, the Admin Area uses a special admin "handler", the Admin User Interface (Admin-UI).

In the Plugin Manager you will find something called "Plugin Builder". It allows you to select your e107 *_sql 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 plugin.xml meta-file, which is used during installation of your plugin.

👍 It is strongly recommended for plugin developers to upgrade their Admin Area using the Plugin Builder.

Plugin Builder

Migrating plugin preferences

👍 In e107 v.2x, it is strongly recommended for plugins to save their preferences in their own table row. Older plugins may still store plugin preferences in the core preference table.

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:

$oldPluginPrefs = array(
    'myplugin_caption' => 'caption', // old-pref-name => new-pref-name 
    'myplugin_display' => 'display',
    'myplugin_maxage'  => 'maxage',
);

if($newPrefs = e107::getConfig()->migrateData($oldPluginPrefs,true)) // returns new array with values and deletes core pref. 
{
    $result = e107::getPlugConfig('myplugin')->setPref($newPrefs)->save(false,true,false); // save new prefs to 'myplugin'. 
}