MyBB Community Forums

This tutorial will focus on how to use templates in your plugins in a better way than what is currently "standard". Many plugin authors currently implement their plugins with templates added to the global templates (sid = -1) and just remove them by name. This can make updating a plugin a bear when it removes your template - with all your existing modifications to it - during the upgrade process. This method eliminates that, and in addition inserts the template into each theme instead of into the global templates. It also allows you to use a templategroup to group the templates for your plugin. How nice, eh?

What this means for the user's of your plugin:

• They can have the templates setup different for different themes instead of being locked into the same template for every theme.
  
• If they modify the template and its changed in a new release of the plugin, then they can use the find updated templates feature just like with MyBB's official templates!
  
• In the end the users have more control of how their plugin appears to the members of their sites.
  

Users of my new User Agents plugin are finding this a very nice feature. At least those that are beta testing for me!

Questions/Comments/Suggestions welcome. I fully admit I don't always think of everything. But if you make a comment about something that I've already covered and you didn't bother to read the whole tutorial... I will beat you with a clue-by-four. So don't do it. I'm sick of wasted time answering the same thing over and over like happened in the 1.6.5 Plugin Changes thread. Basically this is no different than RTFM, so RTFP & RTFT (Read the _F_ Post & Read the _F_ Thread!). Please.

Now... on to it!

Installation:
Nothing to do with templates goes here. (See caveat in the activation section)

Is Activated
Nothing to do with templates goes here.

Uninstall
Template Group removal goes here.
Example:

function pluginname_uninstall()
{
	global $db;
	
	$db->delete_query("templategroups", "title = 'My Template Group Name'");
}

Activate
Template group creation, if it doesn't exist! We don't do this in the install function because that would break the ability to update from a previous version of the plugin that doesn't include a templategroup, but does include (the proper way!) all settings added & removed via install/uninstall as they would lose all their settings. If this is a brand new plugin, I suggest placing this in the install without the if wrapper.
Example:

function pluginname_activate()
{
	global $db;
	
	$q = $db->simple_select("templategroups", "COUNT(*) as count", "title = 'My Template Group Name'");
	$c = $db->fetch_field($q, "count");
	$db->free_result($q);
	
	if($c < 1)
	{
		$ins = array(
			"prefix"		=> "mytemplateprefix",
			"title"			=> "My Template Group Name",
		);
		$db->insert_query("templategroups", $ins);
	}
}

Template creation. This is a pretty standard thing in plugins, and with this method you need to have these in the activate function, not install, so that they can just deactivate then activate to update the plugin! Note the version numbers here! I'm starting at 1600 (for MyBB 1.6 series), and any time you modify the template you increase the version by 1. Otherwise... don't mess with it! Also note that I'm using -2 for my sid, this is important for this method.
Example:

function pluginname_activate()
{
	global $mybb;
	
	$ins = array(
		"tid"			=> NULL,
		"title"			=> 'mytemplateprefix_Template 1',
		"template"		=> $db->escape_string('some template html stuff here'),
		"sid"			=> "-2",
		"version"		=> $mybb->version + 1
		"dateline"		=> time(),
	);
	$db->insert_query("templates", $ins);
	
	$ins = array(
		"tid"			=> NULL,
		"title"			=> 'mytemplateprefix_Template 2',
		"template"		=> $db->escape_string('some other html here'),
		"sid"			=> "-2",
		"version"		=> $mybb->version + 1,
		"dateline"		=> time(),
	);
	$db->insert_query("templates", $ins);
}

Deactivate
Here we simply remove the templates we added in the activate function. Very very simple.
However it is important to do it the right way. Note the use of IN() for the list of template names, but then after it we also have AND sid='-2', you cannot forget that part, or you will remove the user modified versions of the template as well!
Example

function pluginname_deactivate()
{
	global $db;
	
	$db->delete_query("templates", "title LIKE 'mytemplateprefix_%' AND sid='-2'");
}

Notes:
Things I did not yet address with this include:

• User modified templates are never removed. I figure end users can do this manually. This is for those rare occasions where you have to reinstall the plugin to update because it has new settings added.
  
• The addition of a new function for plugins called "puginname_update()" since MyBB's core doesn't currently support it. I think that when I have free time I'll write in support for this in MyBB's plugin class. We need it.
  

I have been doing something similar in my plugins that are more complex in the template area. MyShowcase creates a new language dependent template group with SID = -2 for the same reasons you mention.

However, I put all the new templates in the install and remove in uninstall and the template edits in activate and remove them in deactivate. I prefer this method as I include an upgrade file with my big plugins that has code that runs in each of the install/uninstall and activate/deactivate but this is likely overkill for most plugins.

However, tracking the plugin version in the cache is important so that you can tell what you are upgrading from, then the upgrade script for the plugin can do a version comparison and upgrade on a per release method. This is for another topic though.

Back to your post, the version thing in the templates does not work though, since MyBB writes the MyBB version (e.g. 1605) as the version number every time you save a template, custom or default regardless.

Ah, I didn't know about MyBB auto-changing the version like that. Beh. Whats the point then?

The rest of your suggestions are valid though, especially the SID=-2 and creating new template groups when you have a lot of them

(2012-01-14, 04:55 AM)pavemen Wrote: [ -> ]The rest of your suggestions are valid though, especially the SID=-2 and creating new template groups when you have a lot of them

I only meant whats the point of actually versioning the things

Nice guide Dylan One thing I would like to mention that I do that (IMO) makes life easier is to use a like query for removing templates. Since you're using a template group, the templates should all have the same prefix, so you can just to:

$db->delete_query("templates", "title LIKE 'prefix_%' AND sid='-2'");

If you have a lot of templates for your plugin, this is much easier than writing every title out.

---

Just noticed something else, why do

if(!($c > 0))

When one can do

if(c < 1)

? Doesn't make much sense

I copied and pasted from my plugin, which I wrote while suffering insomnia. But you're right it doesn't make much sense lol! I'll edit the first post. Also, yes your suggestion on the SQL for template removal is valid. I'll add that at as well.

(2012-01-14, 08:22 AM)Dylan M. Wrote: [ -> ]

(2012-01-14, 04:55 AM)pavemen Wrote: [ -> ]The rest of your suggestions are valid though, especially the SID=-2 and creating new template groups when you have a lot of them

I only meant whats the point of actually versioning the things

It would be nice if the version was two part. One part is the MyBB version it is based on and the other is the template version, incrementing on each save. A nice option would be to save new (increment) or save overwrite (self-explanatory)

I'm adding this to PluginLibrary. $PL->templates() creates a template group and puts one or more templates in it, and (if already present) updates the templates and (if user edited it before that) makes it show up in MyBB's Find Updated Templates. The user has to figure out the changes by himself using MyBB's diff report though. Templates no longer in use are deleted. $PL->templates_delete() removes one (or more) template groups and their templates.

Semantics wise this creation/updating/deleting works the same way as with $PL->settings() which already does the same for managing setting groups. There is no need for a version / update routine in the plugin itself, it just treats any change as an update in either direction.

I've already pushed the code to GitHub, if you want to take a look at it - but I'm not done testing yet so there may still be bugs in it. I'm hoping to release this by the end of the week. I'll be using this in the next version of the Overview plugin, which currently has several templates in the global scope. With the new method it'll be easier to handle and adaptable for each theme individually.

I'm glad people are finding this useful