e107 v2.x Plugin and Theme developer manual.

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

		require_once("class2.php");
require_once(HEADERF);
echo "Hello World";
require_once(FOOTERF);

Then point your browser to www.yoursite.com/test.php

Your code should not produce any PHP warnings or notices during normal use. 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. Many PHP notices can be avoided by using the functions vartrue() and varset().

We recommend this collection of Firefox Addons. The most important being the e107 Debugger. If you don't wish to use the debugger, you can still activate various debugging modes manually, by changing the query string of the url. ie. directly after .php? add [debug=xxxx]

Retrieving the database class object

		$sql = e107::getDb();

select()

Selecting data from a database table:

		$sql = e107::getDb();
$sql->select('tablename', 'field1, field2', 'field_id = 1');

fetch()

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

		$sql = e107::getDb();
$sql->select('tablename', 'field1, field2', 'field_id = 1');
while($row = $sql->fetch())
{
    echo $row['field1'];
}

insert()

Inserting data into a database table:

		$insert = array(
    'user_id' => 1,
    'user_email' => '@'
);

$sql->insert('user', $insert); // where 'user' is the table name

update()

Updating information in a database:

		$update = array(
    'user_email' => '@',
    // ... Long list of fields/values
    'WHERE' => 'user_id = 1'
);

$sql->update('user', $update); // where 'user' is the table name.

retrieve()

Combined select() and fetch() method.

Example: Get single value

		$string = $sql->retrieve('user', 'user_email', 'user_id=1');

Example: Get multiple table-row values

		if($allRows = $sql->retrieve('user', 'user_name, user_email', '', true))
{
	foreach($allRows as $row)
	{
		echo $row["user_name"]." - ".$row["user_email"]."<br/>";  
	}
}

delete()

Delete a record from a database table.

		$sql->delete("user", "user_id=2");

gen()

Generic query function

Example: perform a JOIN with gen():

		$sql->gen("SELECT f.*,u.user_name FROM #faqs AS f LEFT JOIN #users as u ON f.faq_author = u.user_id ");

Retrieving the form class object

		$frm = e107::getForm();

Basics

open()

Returns a form opening tag.

		$frm->open('myform'); // returns

		$frm->open('myform', 'get', 'myscript.php', array('autocomplete' => 'on', 'class' => 'formclass'));

close()

Returns a form closing tag

		$frm->close(); // returns 

text()

Returns a text field form element

		$frm->text('my-field', 'current_value', 100, array('size' => 'large')); // returns <input class="tbox input-large" id="my-field" maxlength="100" name="my-field" type="text" value="current_value"></input>

textarea()

		$frm->textarea($name,$value,$rows,$cols,$options,$counter);

bbarea()

		$frm->bbarea($name,$value,$template,$mediaCat,$size,$options);

select()

		$frm->select($name,$option_array,$selected,$options,$defaultBlank);

checkbox()

		$frm->checkbox($name,$value,$checked,$options);

hidden()

		$frm->hidden($name,$value,$options);

button()

		$frm->button($name,$value,$action,$label,$options);

Advanced

carousel() Render a Bootstrap carousel

		$frm->carousel($name, $array, $options);

		$array = array(
      'slide1' => array('caption' => 'Slide 1', 'text' => 'first slide content' ),
      'slide2' => array('caption' => 'Slide 2', 'text' => 'second slide content' ),
      'slide3' => array('caption' => 'Slide 3', 'text' => 'third slide content' )
  );

echo $frm->carousel('my-carousel', $array);

tabs() Render Bootstrap tabs

		$frm->tabs($array,$options);

		$array = array(
   'home' => array('caption' => 'Home', 'text' => 'some tab content' ),
   'other' => array('caption' => 'Other', 'text' => 'second tab content' )
);

echo $frm->tabs($array);

echo $frm->tabs($array, array('active'=>'other')); // make 'other' the initial active tab. 

toHtml()

Parse HTML in various ways. eg. replace constants, convert bbcode etc.

		$tp->toHtml(string, bbcodes, type);
$tp->toHtml("<strong class="bbcode bold bbcode-b bbcode-b-page">Bold print</strong>", true, 'BODY'); // Example

toDate()

Convert a unix timestamp into a readable format.

		$tp->toDate(unixDatestamp, format);

toText()

Convert html to plain text.

		$tp->toText(string);

createConstants()

Convert e_xxxxx paths to their equivalent shortcodes. eg. e_PLUGIN becomes {e_PLUGIN}

		$tp->createConstants(string);

replaceConstants()

Convert {e_XXXX} shortcode paths to their equivalent constants. eg. {e_PLUGIN} becomes e_PLUGIN

		$tp->replaceConstants(string);

parseTemplate()

Parse an e107 template using core and/or custom shortcodes. ie. replaces all instances of {XXXXX_XXXX} etc.

		$tp->parseTemplate(template, use core shortcodes, custom shortcodes);

thumbUrl()

Use to convert {e_MEDIA_IMAGE} and other image paths to an auto-sized image path for use inside an img tag.

		$url = "{e_MEDIA_IMAGE}2012-04/someimage.jpg";
$image = $tp->thumbUrl($url);
echo "<img src='".$image."' />

setThumbSize()

Set the width, height and crop of the thumbUrl function.

		$tp->setThumbSize($width, $height, $crop);

toGlyph()

Convert a glyph name into Html. Just choose an icon from font-awesome and remove the first 'fa'
Templates may also use the following shortcode: which calls the same function.

		$tp->toGlyph("fa-anchor");

Advanced settings:

		$tp->toGlyph("fa-anchor", array('size'=>'2x'));

toIcon()

Render an icon. If a .glyph extension is found, it will automatically use the toGlyph() function above.

		$iconPath = "{e_MEDIA}myicon.png";
$tp->toIcon($iconPath);

toAvatar()

Render a user avatar. If empty, the current user's avatar will be displayed if found or a generic avatar image.

		echo $tp->toAvatar(); // render avatar of the current user. 

		$userData = e107::user(5);  // Get User data for user-id #5. 
echo $tp->toAvatar($userData); // requires as a minimum $userData['user_image'].

toImage()

Render an image.

		$url = "{e_MEDIA_IMAGE}2012-04/someimage.jpg";
$parms = array('w'=>500, 'h'=>200,'crop'=>1, 'alt'=>'my image'); // if not width/height set, the default as set by {SETIMAGE} will be used.
echo $tp->toImage($url,$parms); 

Send HTML to the browser.

		$ns = e107::getRender();
$ns->tablerender($caption, $text, $mode, $return);

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

		e107::pref(type, value);

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

		$myprefs = e107::pref('faqs'); // returns an array.

Or load a single preference value.

		$perPage = e107::pref('faqs', 'faqs_per_page');

Basics

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

		e107::js(type, value, dependency, zone);

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

		e107::js('faqs','js/faqs.js', 'jquery')

Example: Load a theme script in the footer

		e107::js("theme", "js/scripts.js", 'jquery');  // no 'zone' value, loaded in the footer by default. 

Example: Load a theme script in the header

		e107::js("theme", "js/scripts.js", 'jquery', 2); // including a 'zone' value loads it 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.

Remember that loading from url may take more time than local resources, remember to use dependency if needed

JavaScript Behaviors

Behaviors are event-triggered actions that attach to page elements, enhancing default non-JavaScript UIs. Behaviors are registered in the e107.behaviors object using the method 'attach' and optionally also 'detach' as follows:

		var e107 = e107 || {'settings': {}, 'behaviors': {}};

(function ($)
{
  e107.behaviors.myBehavior = {
    attach: function (context, settings)
    {

    },
    detach: function (context, settings, trigger)
    {

    }
  };
})(jQuery);

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.

		(function ($) {
  // All your code here.
})(jQuery);

If you don't, you may see the 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.

		var e107 = e107 || {'settings': {}, 'behaviors': {}};

(function ($)
{

  e107.behaviors.myBehavior = {
    attach: function (context, settings)
    {
      $(context).find(".some-element").once('my-behavior').each(function ()
      {
        // All your code here.
      });
    }
  };

})(jQuery);

Settings passed locally to JavaScript Behaviors

		e107.behaviors.myBehavior = {
  attach: function(context, settings) {
    $('#example', context).html(settings.myvar);
  }
};

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

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

		e107::css(type, value);

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.

		e107::user($user_id);
$userData = e107::user(USERID); // Example - currently logged in user. 
$userData = e107::user(5); // Example  User ID #5.

e107::meta($name, $content, $extended);
e107::meta('keywords','some words'); // example
e107::meta('apple-mobile-web-app-capable','yes'); // example

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

From e107 v2.1.2 you can use e_event.php to catch the events in order of using e_module.php

		e107::getEvent()->register(name, function, include);

Example 1: trigger myFunction() on user login.

		//
e107::getEvent()->register('login', 'myFunction'); 

function myFunction($data)
{
   // do something    
}

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

		e107::getEvent()->register('login', 'myFunction',  e_PLUGIN."myplugin/myFunctions.php");

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

		e107::getEvent()->register('login', array('myClass', 'myMethod'),  e_PLUGIN."myplugin/myClass.php");

User Event Triggers

Custom page

News

Private Messenger

Forum

Admin Event Triggers

Admin changes their password

Comments Manager

Downloads

News

Pages

Users

You can assign and render 'alert' messages using the following.

		$mes = e107::getMessage();

addSuccess()

		$mes = e107::getMessage();
$mes->addSuccess('You did it!');

addError()

		$mes = e107::getMessage();
$mes->addError('There was a problem!');

addWarning()

		$mes = e107::getMessage();
$mes->addWarning('You do not have access to this area!');

addInfo()

		$mes = e107::getMessage();
$mes->addInfo('Please take note!');

addDebug()

Messages assigned here will only be displayed when debug mode is active.

		$mes = e107::getMessage();
$mes->addInfo('Please take note!');

render()

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

		$mes = e107::getMessage();
$mes->addInfo('Please take note!');
echo $mes->render();

$log = e107::getLog();

add()

$log = e107::getLog();
$log->add(name, details, type, code);

//Example: 
$log->add('My Event Name', $myDetailedData, E_LOG_INFORMATIVE, 'MYCODE');

You can redirect to a url using the following static method:

		e107::redirect(url);

To redirect to the home page, simply leave the url blank.

		e107::redirect();

To redirect to the admin area, use the value 'admin'.

		e107::redirect('admin');

For any other location, include the full url.

		e107:redirect("http://my-domain.com/myfile.php");
exit;

You can generate a search-engine-friendly URL (where supported) using the following method:

		e107::url(plugin, key, row, options);

Example

In this example we will generate a search-engine-friendly URL for a forum topic with the following code: .

		$data = array(
    'forum_sef'='my-sef-forum-name', 
    'thread_id'=>2, 
    'thread_sef'=>'my-forum-topic'
); // these values are usually loaded from the database. 

$url = e107::url('forum','topic',$data);

The code above loads the following file: e107_plugins/forum/e_url.php and generates a URL from the following array data with the unique key topic:

		$config['topic'] = array(
 'regex' => '^forum/(.*)/(d*)-([w-]*)/???(.*)',
 'sef' => 'forum/{forum_sef}/{thread_id}-{thread_sef}/',
 'redirect' => '/e107_plugins/forum/forum_viewtopic.php?id=$2&$4'
 );

Only the value of 'sef' is used in this array. it substitutes the values {forum_sef}, {thread_id} and {thread_sef} with the variables in the $data array.

The end result would look something like this: http://sitename.com/forum/my-sef-forum-name/2-my-forum-topic

• Create an empty plugin folder in e107_plugins/ (eg. 'myplugin')
  
• Create a new text file with the _sql.php extension. (eg. 'myplugin_sql.php')
  
• Using PHPMyAdmin, create your database table structure, and then export it in SQL format.
  
• Copy/Paste the "CREATE TABLE" data to your your _sql.php file. (see other plugins for examples)
  
• Go to Manage -> Plugin Manager -> Plugin Builder and choose 'myplugin' from the dropdown menu and then follow the prompts.
  
• Thoroughly check the details of each Table Tab (and Preferences Tab if you need them) before proceeding with the creation process.
  

$fields

Database fields are defined by the $fields value in the admin-ui class. Example:

		protected $fields = array(

   'myfield_id'  => array("title"=>"My Title", "type"=>"text", "data"=>"str", "width"=>"auto", "inline"=>true)

   // .....

);

type

data

readParms (list mode)

writeParms (create/edit mode)

		protected $sortField  = 'field1';
protected $sortParent = 'field2';
protected $treePrefix = 'field3';

		protected $sortField  = 'download_category_order';
protected $sortParent = 'download_category_parent';
protected $treePrefix = 'download_category_name';

plugin.xml

Here's a simple example of a plugin.xml file.

		<?xml version="1.0" encoding="utf-8"?>
<e107Plugin name="Newsfeeds" version="2.0" date="2012-08-01" compatibility="2.0" installRequired="true">
	<author name="e107 Inc." url="http://e107.org" email="@" />
	<description>This plugin's description.</description>
	<category>content</category>
	<adminLinks>
		<link url='admin_config.php' description='Configure Newsfeeds' icon='images/icon_32.png' iconSmall='images/icon_16.png' >LAN_CONFIGURE</link>	
	</adminLinks>
	<siteLinks>
		<link url="/e107_plugins/newsfeed/newsfeed.php" >Newsfeeds</link>
	</siteLinks>	
</e107Plugin>

Here's an advanced example of a plugin.xml file.

		<?xml version="1.0" encoding="utf-8"?>
<e107Plugin name="FAQs" version="1.1"  lan="LAN_PLUGIN_XXX_NAME" date="2012-08-01" compatibility="2.0" installRequired="true">
	 <author name="e107 Inc" url="http://www.e107.org" email="@" />
	<summary>Add frequently asked questions to your e107 website.</summary>
	<description  lan="LAN_PLUGIN_XXX_DESCRIPTION">A simple plugin to add Frequently Asked Questions to your website.</description>
	 <copyright>Copyright e107 Inc e107.org, Licensed under GPL</copyright>
	<category>content</category>
	<keywords>
		<word>faq</word>
		<word>question</word>
		<word>answer</word>
	</keywords>
	<adminLinks>
		<link url='admin_config.php' description='Configure FAQs' icon='images/icon_32.png' iconSmall='images/icon_16.png' primary='true'>LAN_CONFIGURE</link>		
	</adminLinks>
	<siteLinks>
		<link url='/e107_plugins/faqs/faqs.php' description='FAQs' icon='images/icon_32.png' iconSmall='images/icon_16.png' function="faqCategories">LAN_PLUGIN_FAQS_NAME</link>		
	</siteLinks>
	<pluginPrefs>
		<pref name="add_faq">255</pref>
		<pref name="submit_question">255</pref>
		<pref name="classic_look">0</pref>
	</pluginPrefs>
	<dependencies>
		<plugin name='chatbox_menu' />
		<plugin name='calendar_menu' min_version='3.70' />
		<PHP name='core' min_version='5.2.5' />
		<MySQL name='server' min_version='4.9' />
		<extension name='curl' min_version='1.3' />
		<extension name='mb_string' />
	</dependencies>
	<userClasses>
		<class name="faq_moderator" description="FAQ moderator" />		
	</userClasses>
	<extendedFields>
		<field name="viewed" type='EUF_TEXTAREA' default='0' active="true" />
		<field name="posts" type='EUF_INTEGER' default='0' active="true" />
	</extendedFields>	
</e107Plugin>

plugin_setup.php

More details coming soon. See e107_plugins/gallery/gallery_setup.php for an example.

plugin_sql.php

This contains a "CREATE TABLE" mysql dump of the database tables that your plugin will use.
You can find examples in most of the plugins in e107_plugins/

File Types

Defining Language Terms aka 'LANS'

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() for variables where needed. See the examples below:

Good:

		define("LAN_XXX", "Thank you Firstname");
define("LAN_XXX", "Go to [x] to see the results."); // Good - replace [ and ] with <a href='...'> and </a> using str_replace()
define("LAN_XXX", "I want to [quote] here"); // Good - replace [ and ] with " " using str_replace()

Bad:

		define("LAN_XXX", "Thank you <b>Firstname</b>"); //Bad contains HTML
define("LAN_XXX", "Thank you <a href='http://somewhere.com'>Firstname</a>"); //Bad contains HTML
define("LAN_XXX", "Thank you Firstname"); //Bad - allows translator to modify link.

Avoid short language strings for words such as 'and', 'to' and so on. There aren't always equivalents in other languages. If embedding values into a phrase, use substitution. Avoid using substitution terms which are real words or known bbcodes.

		define("LAN_EXAMPLE_01", "Update results: [x] records changed, [y] errors, [z] not changed");
$repl = array($changed,$errors,$unchanged);
$text = $tp->lanVars(LAN_EXAMPLE_01,$repl);

Loading Language Files

To load a language file from a plugin folder:

		e107::lan('faqs');
e107::lan('faqs',true);
e107::lan('faqs',false, true);
e107::lan('faqs',true, true);

Will include the following paths:

		e107_plugins/faqs/languages/English_front.php
e107_plugins/faqs/languages/English_admin.php
e107_plugins/faqs/languages/English/English_front.php
e107_plugins/faqs/languages/English/English_admin.php

e107 plugin "addons" are files which reside in each plugin's folder and allow a plugin to embed itself inside e107's core pages and functions.
You can recognize these files by their e_xxxxx.php naming format.
By simply placing any or all of the file types below inside your plugin's folder, they will be auto-detected during installation and integrated into the system.
If added after installation you may need to run the Scan Plugin Folders option in admin -> Databases.

e_cron.php

Allows a plugin to add additional scheduled task options to e107. (see admin -> Scheduled Tasks)
Be sure to replace plugindir with your plugin's directory name. eg. class faqs_cron

		class plugindir_cron       // plugin-folder name + '_cron'.
{
    function config() // Setup  
    {
        $cron = array();
	
        $cron[] = array(
            'name'            => "Name of my function",  // Displayed in admin area. . 
            'function'        => "myFunction",    // Name of the function which is defined below. 
            'category'        => 'mail',           // Choose between: mail, user, content, notify, or backup
            'description'     => "Description of what my function does"  // Displayed in admin area. 
        );		
		
        return $cron;
    }
	
    public function myFunction()
    {
        // Do Something. 
    }

}

e_dashboard.php

Adds custom plugin information to the dashboard of e107's admin area. The 'latest', 'status' and 'website stats' areas may all contain information from your plugin.
See e107_plugins/forum/e_dashboard.php for an example of usage.

e_event.php (as of e107 v2.1.2)

Allows a plugin to easily hook into system events and trigger their own methods/functions using data provided by those events. (more coming soon)

e_header.php

Allows a plugin developer to add data to the of every page. This file is loaded in the header of each page of your site. ie. Wherever you see require_once(HEADERF) in a script.
It is used to place elements inside the html tags.
Typically you would use one or all of the following functions within this file: e107::js(), e107::css() or e107::meta().
Output should never be echoed or printed from this file.

e_help.php

Allows plugin developers to add information to the plugin configuration page sidebar.

e_latest.php

Deprecated. Use e_dashboard.php instead.

e_mailout.php

Allows your plugin to use e107's mailout feature for bulk mailing.
See e107_plugins/newsletter/e_mailout.php for an example.

e_menu.php

Provide configuration options for each instance of your plugin's menus. Examples can be found in e107_plugins/banner/e_menu.php and e107_plugins/news/e_menu.php

(This is a replacement for the old config.php file used in v1.x)

e_module.php

This file is loaded every time the core of e107 is included. ie. Wherever you see require_once("class2.php") in a script. It allows a developer to modify or define constants, parameters etc. which should be loaded prior to the header or anything that is sent to the browser as output. It may also be included in Ajax calls.

e_search.php

Adds your plugin to the 'search page' of e107.
See e107_plugins/chatbox_menu/e_search.php for an example.

e_meta.php

Deprecated. Use e_header.php instead.

e_notify.php

Adds your plugin to the email notifications admin area. Replace mytrigger with a unique name of your own, and myplugin with your plugin folder.

		class myplugin_notify extends notify // plugin-folder + '_notify' 
{		
	function config()
	{
		
		$config = array();
	
		$config[] = array(
			'name'			=> "New Trigger Name", // Displayed in admin area. 
			'function'		=> "myplugin_mytrigger",
			'category'		=> ''
		);	
		
		return $config;
	}
	
	function myplugin_mytrigger($data) 
	{
	
		$message = print_a($data,true);
		
		$this->send('myplugin_mytrigger', "My Subject", $message);
	}
	
}

Then add the following to your script when you want to trigger it.

		e107::getEvent()->trigger("myplugin_mytrigger", $data);

e_status.php

Deprecated. Use e_dashboard.php instead.

e_rss.php

Adds your plugin to the RSS plugin, and generates RSS feeds for your plugin.

		class chatbox_menu_rss // plugin-folder + '_rss' 
{
    /**
     * Admin RSS Configuration 
     */        
    function config() 
    {
        $config = array();
    
        $config[] = array(
            'name'            => 'Chatbox Posts',
            'url'            => 'chatbox',
            'topic_id'        => '',
            'description'    => 'this is the rss feed for the chatbox entries', // that's 'description' not 'text' 
            'class'            => '0',
            'limit'            => '9'
        );    
        
        return $config;
    }
    
    /**
     * Compile RSS Data
     * @param $parms array    url, limit, id 
     * @return array
     */
    function data($parms='')
    {
        $sql = e107::getDb();
        
        $rss = array();
        $i=0;
                    
        if($items = $sql->select('chatbox', "*", "cb_blocked=0 ORDER BY cb_datestamp DESC LIMIT 0,".$parms['limit']))
        {

        while($row = $sql->fetch())
            {
                $tmp                        = explode(".", $row['cb_nick']);
                $rss[$i]['author']            = $tmp[1];
                $rss[$i]['author_email']    = ''; 
                $rss[$i]['link']            = "chatbox_menu/chat.php?".$row['cb_id'];
                $rss[$i]['linkid']            = $row['cb_id'];
                $rss[$i]['title']            = '';
                $rss[$i]['description']        = $row['cb_message'];
                $rss[$i]['category_name']    = '';
                $rss[$i]['category_link']    = '';
                $rss[$i]['datestamp']        = $row['cb_datestamp'];
                $rss[$i]['enc_url']            = "";
                $rss[$i]['enc_leng']        = "";
                $rss[$i]['enc_type']        = "";
                $i++;
            }

        }                
                    
        return $rss;
    }
            
        
    
}

e_related.php

Adds your plugin to the search which generates 'related' links in news items and pages of e107. See e107_plugins/news/e_related.php for an example.

e_shortcode.php

Sometimes a plugin developers wishes that his shortcode be available not only to his plugin's templates but to core templates and templates of other plugins. This is the purpose of this file. It's content is identical to that of a regular shortcode class except that all the methods must follow the following naming convention:
sc_plugindir_name() eg. sc_faqs_question()

e_sitelink.php

Adds a sitelink sublink-generating function for your plugin. eg. auto-generated navigation drop-down menus for 'latest articles' etc.
See e107_plugins/news/e_sitelink.php for an example.

e_url.php

Provides a simple way to add mod-rewrite redirects to your plugin's page, without having to edit the .htaccess file. To create search-engine-friendly URLs which utilize this addon, please see the e107::url() method.

		class myplugin_url // plugin-folder + '_url' 
{
	function config() 
	{
		$config = array();
	
		$config[] = array(
			'regex'			=> '^myplugref-(.*)/?$',
			'redirect'		=> '{e_PLUGIN}myplugin/ref.php?ref=$1',
		);
				
		return $config;
	}	
}

e_user.php

Adds information about a specific user to the user's profile page. See e107_plugins/forum/e_user.php for a working example.

Your Plugin's Admin Area

We recommend plugin developers to upgrade their admin areas using the 'Plugin Builder' in the 'Plugin Manager" area. It allows you to select your e107 _sql file from your plugin folder, or directly from the database table list 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 and also when sharing plugins via this site. The advantages of using the new admin system are numerous - including, but not limited to:

• No need to code in the HTML or the process of reading or writing to your database.
• Consistent interface with the rest of admin
• Users can select which fields from your db table they wish to view - based on your predefined list.
• Media-Manager is integrated into the system.
• Easily add drag and drop sorting/re-ordering to your plugin.
• Easily add batch delete, copy, featurebox creation, sitelink creation, userclass modification, etc. etc.
• Easily add inline editing to your data.
• Easily add tabs to keep your plugin's admin-area well organized.

Your Plugin's Front End

Minimum Changes:

• Include a plugin.xml file

Recommended Changes:

• Include a plugin.xml file
• Use e107's form_handler class for all form elements.
• Use Bootstrap 3 html/css standards in your templates and/or HTML markup
• Upgrade e_xxxx.php files to v2 standards
• Upgrade language-file names to new standards

Migrating Plugin Preferences to their own table row.

In e107 v.2x we recommend plugins to save their preferences to their own table row, however old plugins may still be storing them in the core preference table.

To easily migrate from one to the other, we created a simple method called migrateData().

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

• 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 Bootstrap documentation and for snippets: bootsnipp.com.
• 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.

This file contains information about the theme. It is used during installation and also during configuration of the theme.
To create a new theme.xml file or derive one from an existing v1.x theme.php file use the conversion tool here: yoursite.com/e107_admin/theme.php?mode=convert
Example from the bootstrap theme:

		<?xml version="1.0" encoding="utf-8"?>
<e107Theme name="bootstrap" version="1.0" date="2012-12-01" compatibility="2.0">
    <author name ="e107 Inc" email="@" url="http://e107.org" />
    <summary>Bootstrap e107 admin theme</summary>
    <description>Bootstrap e107 admin theme</description>
    <category>generic</category>
    <keywords>
        <word>bootstrap</word>
        <word>clean</word>
    </keywords>
    <screenshots>
        <image>preview.jpg</image>
        <image>fullpreview.jpg</image>
    </screenshots>
    <stylesheets>
        <css file="style.css" name="Default"  />
        <css file="css/superhero.css" name="Superhero" />
    </stylesheets>
    <layouts>
        <layout name='default' title='Default' default='true' />
        <layout name='default-home' title='Default Home'>
            <custompages>FRONTPAGE</custompages>	
        </layout>
        <layout name='hero' title='Hero' />
        <layout name='marketing-narrow' title='Marketing Narrow' />
        <layout name='docs' title='Documentation' />
    </layouts>
</e107Theme>

<?php

$LAYOUT['default'] = "
        <header>MY HEADER<header>
        <article>
            {---}
        </article>
    <footer> My Footer </footer>
";

function tablestyle($caption, $text, $mode='') 
{
    echo "<h3>".$caption."</h3>";
    echo $text;
}

?>

<html>
<head>
 // Auto generated title, script, meta and link tags are added here. 
</head>
<body>
    <header>MY HEADER<header><article>
    <h3>Caption of the current page</h3>
    Text of the current page
    </article><footer> My Footer </footer>
</body>
</html>

Including JS, CSS and Meta in the head

Including a language file

e107::lan('theme'); // loads e107_themes/CURRENT_THEME/languages/English.php (when English is selected)

Commonly used core theme shortcodes are listed below.

Usage example:

		$LAYOUT['default'] = "
    <header>{SITENAME}<header>
    <div>{NAVIGATION=main}</div>
    {SETSTYLE=menu}
    <div class='span2'>
    {MENU=1}
    {MENU=contact}
    </div>
    <div class='span10'>
    {SETSTYLE=default}

 {---}

    </div>
    <footer>{SITEDISCLAIMER}</footer>
";

function tablestyle($caption, $text, $mode='')
{
    global $style; // value defined by {SETSTYLE} shortcode. 
 
    switch($style) 
     {
        case 'menu': 
            echo "<h5>".$caption."</h5>";
            echo $text;
        break;

        default: 
            echo "<h2>".$caption."</h2>";
            echo $text;
        break;
    }
    
}

News

Page/Menu

OPTIONAL e107 v2.x removes the need for separate xxxxxx.sc files inside your theme's folder. You can now include all your theme-specific shortcodes in a single file. These shortcodes may be used in the $LAYOUT of your theme.php file. eg. Using the example below: {MY_SHORTCODE} and {MY_OTHER_SHORTCODE}

		class theme_shortcodes extends e_shortcode
{
	
    function sc_my_shortcode()
    {
        return "Something";
    }

    function sc_my_other_shortcode()
    {
        return "Something else";
    }

}

OPTIONAL Adds information and user-selectable options to the theme's configuration page.

		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>
        ";
    }
}

• 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. e107_theme/YOURTHEME/  

Some examples to illustrate this:
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. 

<layout name='custom' title='Custom Pages'>
    <custompages>FRONTPAGE</custompages>
    <custompages>/forum/</custompages>
</layout>

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

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:

		<?php

$MYPLUGIN_TEMPLATE['start'] = "<ul>";
$MYPLUGIN_TEMPLATE['item'] = "<li>{MYPLUGIN_ITEM}</li>";
$MYPLUGIN_TEMPLATE['end'] = "</ul>";

?>

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

		<?php

$MYPLUGIN_TEMPLATE['list']['start'] = "<ul>";
$MYPLUGIN_TEMPLATE['list']['item'] = "<li>{MYPLUGIN_ITEM}</li>";
$MYPLUGIN_TEMPLATE['list']['end'] = "</ul>";

$MYPLUGIN_TEMPLATE['form']['start'] = "<form>";
$MYPLUGIN_TEMPLATE['form']['body'] = "<div>{MYPLUGIN_FORMINPUT}</divi>";
$MYPLUGIN_TEMPLATE['form']['end'] = "</form>";

?>

$template   = e107::getTemplate('myplugin'); // loads e107_plugins/myplugin/templates/myplugin_template.php

$text = e107::getParser()->parseTemplate($template['start'], true, $scObj); 

// or

$text = e107::getParser()->parseTemplate($template['form']['start'], true, $scObj);

class myplugin_shortcodes extends e_shortcode
{
    // Enter Shortcode methods here
}

class myplugin_shortcodes extends e_shortcode
{
    function sc_say_hello($parm='')
    {
       return "Hello ".USERNAME;
    }
}

class myplugin_shortcodes extends e_shortcode
{
    function sc_say_hello($parm)
    {
       return "Hello ".vartrue($parm['name']);
    }
}

class myplugin_shortcodes extends e_shortcode
{
    function sc_say_hello($parm)
    {
       return "Hello ".vartrue($this->var['name']);
    }
}

$sc = e107::getScBatch('myplugin',TRUE); // loads e107_plugins/myplugin/myplugin_shortcodes.php

Parsing the Template

Basic Example

$template   = e107::getTemplate('myplugin', 'form'); // load the 'form' template from the plugin folder. 
$tp = e107::getParser(); // get Parser Class.
$sc = e107::getScBatch('myplugin',true); // get myplugin shortcodes from plugin folder. 

echo $tp->parseTemplate($template['start'], true, $sc); // parse the 'start' part of the 'form' template.

Full Example with loop

$sql = e107::getDb(); // get the database Class. 
$tp = e107::getParser(); // get Parser Class.
$sc = e107::getScBatch('myplugin',true); // get myplugin shortcodes from plugin folder. 

$template   = e107::getTemplate('myplugin', 'list'); // get template array of 'list' from plugin folder. 

echo $tp->parseTemplate($template['start'], true, $sc); // parse the 'start' part of the 'list' template.

$rowArray = $sql->retrieve("SELECT field FROM #myplugin", true);	// load the values from the plugin's database table. 

foreach($rowArray as $row)    // loop through the database results. 
{
	$sc->setVars($row);	    // send the value of the $row to the class. 
	echo $tp->parseTemplate($template['item'], false, $sc);    // parse the 'item' 
}

echo $tp->parseTemplate($template['end'], false, $sc); // parse the 'end' part of the 'list' template.