Using e107's built-in classes and methods.

Database

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

Forms

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'));

Name Description
$name string - form name
$mode string - post | get - 'post' by default
$target string - request URL - e_REQUEST_URI by default
$options array - specify options such as class or autocomplete

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>

Name Description
$name string - name of the text field
$value string - value of the text fieldt
$maxlength integer - specifies maxlength element of the text field
$options array - specify options such as class, size or selectize
size: mini, small, medium, large, xlarge, xxlarge
selectize: array with selectize.js options

textarea()

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

bbarea()

		$frm->bbarea($name,$value,$template,$mediaCat,$size,$options);
Name Description
$name string - Name of the field
$value string - Contents of the field
$template (optional) string - A string defining the button template to use with bbarea. Included in the core are the following: news, submitnews, extended, admin, mailout, page, comment, signature
But you can also use the name of the plugin (e.g. forum) if the plugin provides a bbcode_template.php
$mediaCat (optional) string - Name of the nedia catalog to use (default: _common)
Is only used by tinymce (if installed and used)
$size (optional) string - Size of the bbarea/editor.
Use one of the following values: tiny, small, medium, large (default: large)
$options

(optional) array - Array with options to use with the editor:
id: string - In case the bbarea/editor id should be different to the name
class: string - the css classes to use
counter: boolean - Show a character counter
wysiwyg: boolean/string -

  • False in case you want disable the wysiwyg editor for this field and use the default bbcode editor.
  • True to enable the current installed (and enabled) wysiwyg editor
  • Name of the editor (e.g. tinymce4 or simplemde) to use, in case wysiwyg is generally enabled and the supplied editor is installed.

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. 

Parser

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
Name Description
string text or HTML to be parsed
bbcodes boolean - set to true to parse bbcodes into html
type string - TITLE, SUMMARY, DESCRIPTION, BODY, LINKTEXT, RAWTEXT

toDate()

Convert a unix timestamp into a readable format.

		$tp->toDate(unixDatestamp, format);
Format Description
short Short date format as defined in admin preferences
long Long date format as defined in admin preferences
relative Relative time format. eg. "2 days ago"

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);
Name Description
template string
user core shortcodes boolean
custom shortcodes object

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); 

Render

Send HTML to the browser.

		$ns = e107::getRender();
$ns->tablerender($caption, $text, $mode, $return);
Name Description
$caption string - header/caption
$text string - main content
$mode unique name for what is being rendered. eg contact-menu
$return boolean - when set to true the content is returned instead of being echoed.

Preferences

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');
Type Value (optional)
core all core preference values.
theme preferences of the currently selected front-end theme.
(any plugin folder name) preferences of a particular plugin

Javascript

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 
Type Value Description
core path relative to the core folder Include a core js file in the header of the page
url* full url to javascript filel Include a remote js file in the header of the page
inline javascript code Include raw javascript code in the header of the page
theme path to js file, relative to the current theme's folder Include a theme js file
(any plugin folder name) path to js file, relative to the plugin's folder Include a plugin js file
settings ‡ array (PHP) Adds settings to e107's global storage of JavaScript settings.

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

CSS

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

		e107::css(type, value);
Type Value Description
theme path relative to the theme's folder Include a theme css file in the header of the site
url full url to css file Include a remote css file in the header of the site
inline css code Include raw css code in the header of every page of the site

User Data

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.

Meta

Include meta tags in the html header.

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

Events

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

Variable Description
name The event you wish to hook into. (see table below)
function Your function or class/method to trigger when this event occurs. string for function, or for classes use an array(class,method) .
include include[/code] (optional) path a file to include if required.

		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

Trigger Name Description Data
login User login/signin Array of user data
logout User logout/signout Notice event
user_file_upload User uploads a file Array of file information
user_signup_submitted User submits signup form Array of user data
user_signup_activated User activates newly created account. (email link) Array of user data
user_xup_login User signs in via a social media account. eg. Facebook, Twitter etc. Array of user data
user_xup_signup User creates an account using their social media login. Facebook, Twitter etc. Array of user data
user_profile_display User has viewed a profile Array of data
user_profile_edit User has edited their profile Array of data of user who changed the settings
user_comment_posted User has posted a new comment Array of data
preuserset Before usersettings are updated Array of new user settings ($_POST)
postuserset After usersettings are updated Array of new user settings ($_POST)
userdatachanged After usersettings are updated (same time and data as user_profile_edit) Array of data of user who changed the settings

Custom page

Trigger function Description Data
user_page_item_viewed User has viewed a custom page Array of data

News

Trigger Name Description Data
user_news_item_viewed User viewed a news item Array of data
user_news_submit User submitted a news item Array of data

Private Messenger

Trigger name Description Data
user_pm_sent User has sent a private message Array of data
user_pm_read User has read a private message Array of data

Forum

Trigger Name Description Data
user_forum_topic_created User creates a forum topic Array of data
user_forum_topic_created_probationary New user creates a forum topic Array of data
user_forum_topic_updated User updates a forum topic Array of data
user_forum_topic_deleted User deletes a forum topic Array of data
user_forum_topic_moved User has moved forum topic to a different forum Array of data
user_forum_topic_split User has split the forum topic Array of data
user_forum_post_created User creates a forum post/reply Array of data
user_forum_post_updated User updates a forum post/reply Array of data
user_forum_post_deleted User deletes a forum post/reply Array of data
user_forum_post_report User has reported a forum post/reply Array of data

Chatbox

Trigger function Description Data
user_chatbox_post_created User has posted a chatbox message Array of data (ip and message)

Admin Event Triggers

Admin changes their password

Trigger Name Description Data
admin_password_update Admin updates their password Array containing user_id and time of change.

Comments Manager

Trigger Name Description Data
admin_comment_update Admin updates a comment Array of comment data
admin_comment_delete Admin deletes a comment Array of comment data

Downloads

Trigger Name Description Data
admin_download_create Admin creates a download item Array of download data
admin_download_update Admin updates a download item Array of download data
admin_download_delete Admin deletes a download item Array of download data

News

Trigger Name Description Data
admin_news_create Admin creates a news item Array of news data
admin_news_update Admin updates a news item Array of news data
admin_news_delete Admin deletes a news item Array of news data
admin_news_category_create Admin creates a news category Array of news data
admin_news__category_update Admin updates a news category Array of news data
admin_news_category_delete Admin deletes a news category Array of news data

Pages

Trigger Name Description Data
admin_page_create Admin creates a page/menu item Array of page data
admin_page_update Admin updates a page/menu item Array of page data (new and old)
admin_page_delete Admin deletes a page/menu item Array of page data

Users

Trigger Name Description Data
admin_user_create Admin creates a new user Array of user data
admin_user_update Admin modifies user data Array of user data (new and old)
admin_user_delete Admin deletes a user Array of user data
admin_user_activate Admin activates an unverified user Array of user data
admin_user_loginas Admin logs in as another user Array of user data
admin_user_logoutas Admin logs out as another user Array of user data

Alerts

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();

Logging

You can log events to the admin system logs by using the built in log class.

$log = e107::getLog();

add()

name a title or name for the log event.
details details for the log event - can be either a string of text or an array.
type the type of event. (see table below)
code is a custom reference code for your type of event. It should be short, ALL CAPITALS and not contain spaces.

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

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


Type Description
E_LOG_INFORMATIVE Informational event
E_LOG_NOTICE Notice event
E_LOG_WARNING Warning event
E_LOG_FATAL Fatal event

Redirection

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;

Urls

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

		e107::url(plugin, key, row, options);
Value Type Description
plugin string Folder name of the plugin. (will use data from e_url.php)
key string Unique key
row array array of variable data such as id, title etc. eg. user_id, user_name
options array An associative array of additional options, with the following elements:
'mode': abs | full
'query': An array of query key/value-pairs (without any URL-encoding) to append to the URL.
'fragment': A fragment identifier (named anchor) to append to the URL. Do not include the leading '#' character.

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

Social Links