Extensibility Basics

This document is designed to explain the concepts of building an Advanced Sidebox addon module in its most basic form. For further details, view the entire list of extensibility documents: Extensibility Docs

##Minimum Requirements

For a module to be accepted by Advanced Sidebox as a valid add-on, it must meet these criteria:

1. A file must exist in the modules directory (inc/plugins/asb/modules) named example.php and
2. This file must be a valid PHP file and
3. This file must contain two functions: asb_example_info and asb_example_build_template

replace example with the base_name for your module

If everything is in order, Advanced Sidebox will attempt to load this add-on.

##Module Info

The info function only allows the admin to see your box type and use it. You still need to tell it what to display. (Keep in mind that we are still using the example base-name from the previous example).

###Minimum Info

In the _info() function you will need to name and optionally describe your module and define its type.

function asb_example_info()
{
	return array(
		"title" => 'Your Title Here',
		"description" => 'A description here',
		"version" =>	'1',
		"wrap_content" => true,
		"compatibility" => '2.1',
	);
}

• title - (string) - serves as the default title for side boxes created with this add-on
• description - (string) - is used in the module manager info
• version - (string) - required to maintain module upgrades
• wrap_content - (bool) - false to produce a side box without the default table and expander, true (default) to allow ASB to wrap the side box in a default tborder class table structure
• compatibility - (string) - since 2.1 distinguishes between earlier modules that are no longer compatible with this plugin.

###Optional Info

• settings - (array) an unindexed array of MyBB standard ACP setting definitions
• templates - (array) an unindexed array of MyBB standard ACP template definitions
• xmlhttp - (bool) true to add the ability of AJAX refresh to the module (requires _xmlhttp() function)
• discarded_templates - (array) - for module upgrades that remove previously used templates, an array of the template names

##Template Building

Each ASB module must also contain a _build_template() function. This is the main function used to display the add-on module's side box content. In some cases, there is another function to produce the content and the _build_template() function simply retrieves it from that function so that _xmlhttp() can share the functions return and save coding.

###Example Of Build Function

This is an example of a simple module's _build_template() function (staying with the example base name):

function asb_example_build_template($args)
{
	// retrieve side box box settings
	extract($args);

	// don't forget to declare your variable! will not work without this
	global $$template_var;

	// create the markup and store it in our template variable
	$$template_var = <<<EOF
	<tr>
		<td class="trow1">Same from either side.</td>
	</tr>
EOF;

	// return true if your box has content, false if not
	return true;
}

###Retrieving The Module Settings

In the previous example, I included the standard extract() I use to retrieve the add-on module's particular settings for reference only-- in that given example it is unnecessarily complicated. The contents of the entire function could have been simplified to this:

global $$args['template_var'];
$$args['template_var'] = 'Content';

However when using more than one of the parameters passed in $args, I find that it is easier to follow the code when each variable is stored locally in a readable manner (ie. $template_var and $settings)

####Module Arguments

• $settings - (array) - used when the add-on module has individual settings, passes an associative array of add-on settings
• $template_var - (string) - is the encode base name of the add-on module use to create the unique template variable for each box
• $width - (int) - side box columns (left/right) can have different widths so this value is provided to better size content based on the different value. The appropriate value for the side box's position will be passed
• $script - (string) - the original location the side box was displayed on with environment parameters-- useful for XMLHTTP routines that redirect

###Globalizing The Template Variables

In order for the main implementation of the current script's hook to use the content of a module, the template variable (encoded with some of the side box using your module's properties and some of the properties of your module) must be globalized. Using Variable Variables (thanks @euantor) we can do that with the information passed to the module's _build_template() function (as in the example code above).

###Storing your content

After the content has been produced and is ready to store for ASB to use, you simply need to assign that content to the global variable whose name is stored in $args['template_var']. This can be done directly, but is more often done using a template and the eval() function:

$template_var = $args['template_var'];
global $template_var, $templates;

eval("\$template_var = \"" . $templates->get('template_name') . "\";");

##Validation Check

At the beginning of your module file, use this code to make sure that the file is being required by a valid MyBB instance and that Advanced Sidebox is active.

if(!defined("IN_ASB") || !defined('IN_MYBB'))
{
	die('You are not allowed to directly access this resource.');
}

For a simple example of the basics, look here: Simple Module Example