MyPlaza Development - How Tos

This is an outline to show how to do some neat tricks with MyPlaza functionality, as well as explain some uses.

Handling Help Documents

This is very easy with MyPlaza. All you have to do is set the appropriate language variables in your _lang() function (set the help_myplaza_modulename_name etc), and call add_helpdoc() from your activation function. Then, in the deactivation routine, call remove_helpdoc() For example:

function module_lang()
{
	global $lang;
	$lang->help_myplaza_module_name = 'My Help Document';
	$lang->help_myplaza_module_desc = 'Example Help Document.';
	$lang->help_myplaza_module_document = 'This is an example help document!';
}

function module_activate()
{
	// you may have to load the normal _lang() routine
	myplaza_langload('module', true);
	add_helpdoc();
}

function module_deactivate()
{
	remove_helpdoc();
}

Adding Settings

MyPlaza also makes adding settings easier. MyPlaza and MyBB can automatically retrieve the name and description of settings if you set them in the _lang_admin() function, before making a call to add_settings. Here's an example:

function module_lang_admin()
{
	global $lang;
	$lang->setting_mysetting = 'My Setting';
	$lang->setting_mysetting_desc = 'This is my setting!';
	$lang->setting_mysetting2 = 'My 2nd Setting';
	$lang->setting_mysetting2_desc = 'This is another of my settings!';
}

function module_activate()
{
	add_settings(array(
		array(
			'name' => 'mysetting',
			'optionscode' => 'text',
			'value' => '10'
		),
		array(
			'name' => 'mysetting2',
			'optionscode' => 'text',
			'value' => '200'
		)
	));
}

MyPlaza will handle everything else (ie escaping), plus, will perform multi-row insert optimizations as a bonus :P

Adding Templates

Yeap, MyPlaza makes this easier too :P Here's an example:

function module_activate()
{
	$new_templates = array(
		'sometemplate' => 'This is a custom template!',
		'anothertemplate' => 'This is another template! :)'
	);
	add_templates($new_templates);
}

MyPlaza will automatically escape the templates for you, plus will also insert the templates using it's own multi-row insert optimizations :P

Passive Hooking

Passive hooking allows MyPlaza to help optimize your modules by only include'ing them when really necessary. With MyBB's plugin system, each active plugin must be include'd on every page load, meaning the PHP parser has to go through it and parse it on every page load. Obviously, this is a waste if you've really only got a hook to a rarely used function.
Passive hooks are added at activation (you'll need to remove them at deactivation too). Adding a passive hook is almost like adding a normal hook. Here's an example:

function module_activate()
{
	plugins_add_passive_hook('xmlhttp', 'module_handle_ajax');
	// you can further optimize this system, if your hook is only executed in the AdminCP, by
	//  supplying true as the fourth argument.
	plugins_add_passive_hook('myplaza_admin_start', 'module_handle_admin', 10, true);
}

function module_deactivate()
{
	plugins_remove_passive_hooks();
}

In the above code, the module will only be included and executed for AJAX functions, and in the AdminCP, rather than every single page on your forums. (note that if you specify a _plugin() function, the module will still be include'd on every page).

Changing a user's money

Just simply make a call to user_change_money(). This is internally optimized, so that multiple calls won't necessarily mean it runs much slower. That is, code like the following will, in fact, only execute as two queries!

// this code will effectively change all users', with a UID between 1 and 100, money to then times
// their UID.
for($i=0; $i<100; $i++)
{
	// first argument is the UID (or user array) and the 2nd argument is the amount to add
	user_change_money($i, $i*10);
}

Note that user_change_money adds to the user's current money. Note that changes are not done immediately (this is how the optimization works), unless you force it to be immediate (supply true as the fourth parameter.

Handling Who's Online List

MyBB isn't exactly that friendly, if you want to add your own Who's Online list entry. Fortunately, MyPlaza makes it much simpler :P Here's an example of handling Who's Online for your own module page:

function module_activate()
{
	plugins_add_passive_hook('myplaza_wol', 'module_wol');
}
function module_deactivate()
{
	plugins_remove_passive_hooks();
}
function module_page()
{
	return 'This is my simple page.';
}
function module_wol(&$text)
{
	global $user;
	if(!isset($user['params']['action']) || $user['params']['action'] != 'page' || !isset($user['params']['p']) || $user['params']['p'] != 'module')
		return;
	
	$text = 'You are viewing my page!';
}