Introduction

Back to the developer docs index

This document contains information on how you can write your own Nucleus plugins

Table Of Contents

• Introduction
• Writing your first plugin
• Overview of the NucleusPlugin class
• The <%plugin(...)%> skinvar
• The <%plugin(...)%> templatevar
• Actions using action.php
• Events, and subscribing to them
• Saving options
• Database tables
• Providing an admin area
• Providing a helppage
• Plugin Dependency Check
• Internationalizing a Plugin
• Formatting Output of SkinVars
• Additional Reading

Introduction

Nucleus plugins allow just about anyone to extend the functionality that Nucleus offers, without having to alter the PHP code itself. Plugins are simple php scripts that must implement certain methods, and can easily be exchanged between Nucleus users. Installing goes as easy as adding the plugin file to the plugin directory and letting Nucleus know it's there.

Some advantages of plugins are listed below:

• Extra functionality can easily be added to the Nucleus framework, without having to know much details about the implementation.
• You can install only the plugins you need, saving on the time needed to generate a page

All plugin files should be placed in the directory that is listed in config.php. Commonly, this will be /your/path/nucleus/plugins/. Plugin files can be recognized by their form: NP_name.php. Some plugins require a subdirectory with the same name to store extra files or their admin area.

Writing your first plugin

Ok, lets start by writing a simple plugin. Basically, each plugin is a PHP class that inherits from the predefined class NucleusPlugin. Below is an example of a HelloWorld-plugin:

<?php

class NP_HelloWorld extends NucleusPlugin
{
	// name of plugin
	function getName()
	{
		return 'Hello World';
	}

	// author of plugin
	function getAuthor()
	{
		return 'Wouter Demuynck';
	}

	// an URL to the plugin website
	// can also be of the form mailto:foo@bar.com
	function getURL()
	{
		return 'http://nucleuscms.org/';
	}

	// version of the plugin
	function getVersion()
	{
		return '1.0';
	}

	// a description to be shown on the installed plugins listing
	function getDescription()
	{
		return 'Just a sample plugin.';
	}

	function doSkinVar($skinType)
	{
		echo 'Hello World!';
	}

	function supportsFeature ($what)
	{
		switch ($what)
		{
			case 'SqlTablePrefix':
				return 1;
			case 'SqlApi':
				return 1;
			default:
				return 0;
		}
	}

}
?>

1. Copy this code in a file called NP_HelloWorld.php, and put it in your plugins directory. Make sure that there are no spaces after the last ?> or before the first <?php.. NP stands for "Nucleus Plugin", if you were wondering about that.
2. Open the Nucleus Administration area and go into Nucleus Management/Manage Plugins
3. You'll find out that there's a HelloWorld plugin you can install. Do this. If everything worked out correctly, you'll see that your plugin is now listed in the list of installed plugins.
4. Now edit one of your skins and insert the following statement at a place of which you know where it will show up on the actual page.

   <%HelloWorld%>

   Note that the name (HelloWorld) is case sensitive!
5. Now visit a page that uses the skin you edited: notice the "Hello World" at the location where you've added the plugin-skinvar.

So, that wasn't so hard after all. Read on to find out more.

The class NucleusPlugin

All Nucleus plugins must inherit from the PHP class NucleusPlugin. If this sounds complicated, don't worry, it isn't. It even makes your life easier, allowing you to only implement the methods that your plugin needs, and giving access to some auxiliary functions.

Below is an overview of the methods that the NucleusPlugin offers, and that you can re-implement in your own plugin. If you want to see the source of the class itsself, it's located at nucleus/libs/PLUGIN.php

Next to the methods that can be implemented, the class NucleusPlugin offers some extra methods which you should not implement yourself. They can be called from within your plugin using the $this->functionName() syntax.

Skinvars

Description

You can create your own skinvars, and call them using <%plugin(PlugName,parameters)%> or <%PlugName(parameters)%> (when this does not conflict with an existing skinvar). Parameters are comma-separated.

To handle skinvars, you'll need to implement the doSkinVar method. Some samples of signatures are given below:

function doSkinVar($skinType)
function doSkinVar($skinType, $param1, $param2)
function doSkinVar($skinType, $skinVar, $param1, $param2)
function doSkinVar($skinType, $skinVar, $param1 = 'default value')

• The $skinType parameter will be one of 'index', 'item', 'archive', 'archivelist', 'member', 'error', 'search', 'imagepopup' or 'template'
• The $skinVar is actually the first parameter that's being interpreted as a type of skinvar (e.g. <%plugin(PlugName,VarType)%>)
• You can use doSkinVar() (no parameters) and retrieve the parameters using the PHP function func_get_args(). Could be handy if you have different types of skinvars with different numbers of arguments

Notes

• (v2.0b) You can find the name of the skin that's currently being parsed in the global variable $currentSkinName

Template variables

Description

Template plugin variables work in the same way as skin plugin vars. There are two differences:

1. They are called from within templates instead of from within skins
2. They don't take a $skinType parameter. Instead, they take extra parameters with info on the item and comment that is currently being parsed:
   • The doTemplateVar-method gets a &$item parameter.
   • The doTemplateCommentsVar-method gets an &$item parameter as well as a &$comment parameter.
   Note the ampersands!

Template variables are called in exactly the same way as skinvars (using <%plugin(PlugName,parameters)%> or <%PlugName(parameters)%>)

By default, all template variables are passed on to the doSkinVar-method, using 'template' as skinType-parameter.

If you want to provide your own implementation, you'll need to redefine the method doTemplateVar and/or doTemplateCommentsVar. It works in the same way as doSkinVar, except that now the skinType-parameter is missing.

function doTemplateVar(&$item)
function doTemplateVar(&$item, $param1, $param2)
function doTemplateVar(&$item, $type, $param1, $param2)
function doTemplateVar(&$item, $type, $param1 = 'default value')
function doTemplateCommentsVar(&$item, &$comment)
function doTemplateCommentsVar(&$item, &$comment, $param1, $param2)
function doTemplateCommentsVar(&$item, &$comment, $type, $param1, $param2)
function doTemplateCommentsVar(&$item, &$comment, $type, $param1 = 'default value')

Notes

• (v2.0b) You can find the name of the template that's currently being used inside the global variable $currentTemplateName

Actions

Plugins can perform actions through action.php, the same script that's being used to receive comments and karma votes. You can call it using both GET and POST methods. Required parameters are action (should be 'plugin'), name (name of the plugin) and type (type of requested action)

To enable these actions, you should implement the doAction($actionType) method in your plugin. Extra parameters from the request can be received using requestVar('name') (requestVar takes care of magic_quotes_gpc that PHP might have added)

When your doAction method returns a string, it will be interpreted as an error, and an error message will be shown.

Events

Nucleus Plugins can subscribe to events that occur whenever something important happens. The plugin can then execute some actions, or output some text.

Example

Below is an example of how a plugin subscribes to the PreAddComment-event, an event that is generated immediately before a comment is added to a blog.

class NP_Acronyms extends NucleusPlugin {
  ...
  function getEventList() { return array('PreAddComment'); }
  ...
  function event_PreAddComment(&$data) {
	// replace acronym HTML
	$data['comment']['body'] =
		strreplace('HTML',
				   '<acronym title="HyperText Markup Language">HTML</acronym>',
				   $data['comment']['body']);
  }
}

This plugin replaces the text HTML in each comment by the text <acronym title="HyperText Markup Language">HTML</acronym>. The acronym-tag is a HTML-tag that allows authors to provide extra information on acronyms.

Subscribing to events

Here's the steps you need to take to subscribe to an event:

1. Add the event name to the array returned by the getEventList-method
2. Create a method with signature event_EventName($data), in which the handling of the event is done

Multiple plugins can subscribe to the same event. The order in which these plugins are notified is the same order as the ordening in the plugin list of the admin area. Plugins higher in the list get notified earlier on.

Parameters

The event_EventName-method gets only one parameter, $data, of which the contents differs depending on the event. It is an associative array with data. Objects and arrays that are passed in this array, are passed by reference, so the changes you make there will be remembered.

The event list below uses some colors to indicate if changes in the parameters will be seen by nucleus or not:

• pass-by-reference: when changes are made to this kind of parameters, they will be seen by Nucleus.
• pass-by-value: a copy of the value is made before it is sent to the plugin event handler. Changes in the contents of these variables will be discarded automatically.

Objects that are passed as parameters are indicates as follows: object. Most objects are also passed by reference, making them look like object by ref

Event List

<h3>plugin name</h3>
<p>your stuff</p>

<h4>plugin name</h4>
<form method="post" action="..."><p>
your stuff
</p></form>

<h4>plugin name</h4>
<form method="post" action="..."><p>
your stuff
</p></form>

<h4>plugin name</h4>
<form method="post" action="..."><p>
your stuff
</p></form>

Saving options

A series of methods are offered to make it easy for plugins to set and retrieve options. These options can be directly edited from inside the Nucleus admin area, taking the need away for the plugin to provide an admin area of its own, and avoiding that options need to be set inside the PHP file itself.

Options are available in different contexts:

1. Global options: Editable on the admin area from the plugins section.
2. Blog options: Editable from the blogsettings pages.
3. Category options: Editable from the blogsettings pages (on the 'edit category' page).
4. Member options: Editable on the 'edit member' pages
5. Item options: Editable on the 'add item' or 'edit item' pages

Option types

Several types of options are provided

text

Simple text

yesno

Either the value 'yes' or the value 'no' (on edit, shown as radio button)

password

Text field (starred on edit)

textarea (v2.2)

Text field with multiple rows and columns

select (v2.2)

Drop down menu. Needs extra info in the following form: Option 1|value1|Option 2|value2|Option 3|value3

Option meta

As of Nucleus v3.2, some option types can be limited to only accept certain values using option-metadata. This metadata is stored in the $typeExtras-field, and is a semicolon-seperated list of values. Note: In a select-option, the select list must be the first value in $typeExtras.

some examples:

// following code creates a text-option that only accepts numerical values
$this->createBlogOption('FooBar', 'foobar', 'text', '0', 'datatype=numerical');
// following code creates a select-option that only accepts numerical values
$this->createItemOption('FooBar', 'foobar', 'select', '0', '0|0|1|1|2|2;datatype=numerical');
// following code creates a textarea-option that is readonly
$this->createOption('FooBar', 'foobar', 'textarea', 'This textarea is readonly', 'access=readonly');

Restrictions

1. The name of an option can contain a maximum of 20 characters
2. The description of an option can contain a maximum of 255 characters
3. The value for an option has no limit (Prior to v2.5 the limit was 128 characters)
4. The characters '=', '|' and ';' can not be used inside a select list (for a select-option), or in option-metadata

The methods

createOption($name, $desc, $type, $defValue = '', $typeExtras = '')

Creates a new option in the global context

[v2.2] createBlogOption($name, $desc, $type, $defValue = '', $typeExtras = '')

Creates an option in the blog context (see createOption)

[v2.2] createCategoryOption($name, $desc, $type, $defValue = '', $typeExtras = '')

Creates an option in the category context (see createOption)

[v2.2] createMemberOption($name, $desc, $type, $defValue = '', $typeExtras = '')

Creates an option in the member context (see createOption)

[v3.2] createItemOption($name, $desc, $type, $defValue = '', $typeExtras = '')

Creates an option in the item context (see createOption)

setOption($name, $value)

changes the value of an option that was already in the database

[v2.2] setBlogOption($blogid, $name, $value)

Changes the value for a blog option. The blogid attribute indicates for which blog the option is valid. (other options: see setOption)

[v2.2] setCategoryOption($catid, $name, $value)

Changes the value for a category option. The catid attribute indicates for which category the option is valid. (other options: see setOption)

[v2.2] setMemberOption($memberid, $name, $value)

Changes the value for a member option. The memberid attribute indicates for which member the option is valid. (other options: see setOption)

[v3.2] setItemOption($itemid, $name, $value)

Changes the value for an item option. The itemid attribute indicates for which item the option is valid. (other options: see setOption)

getOption($name)

Returns the value for an option in the database

[v2.2] getBlogOption($blogid, $name)

Returns the value for a blog option. blogid indicates for which blog a value is requested (other parameters: see getOption)

[v2.2] getCategoryOption($catid, $name)

Returns the value for a category option. catid indicates for which category a value is requested (other parameters: see getOption)

[v2.2] getMemberOption($memberid, $name)

Returns the value for a member option. memberid indicates for which member a value is requested (other parameters: see getOption)

[v3.2] getItemOption($itemid, $name)

Returns the value for an item option. itemid indicates for which item a value is requested (other parameters: see getOption)

deleteOption($name)

Deletes an option from the database

[v2.2] deleteBlogOption($name)

Deletes a blog option (see deleteOption)

[v2.2] deleteCategoryOption($name)

Deletes a category option (see deleteOption)

[v2.2] deleteMemberOption($name)

Deletes a member option (see deleteOption)

[v3.2] deleteItemOption($name)

Deletes an item option (see deleteOption)

[v2.2] getAllBlogOptions($name)

Returns all values for a given blog option. The result is an associative array with a value for each existing blogid

[v2.2] getAllCategoryOptions($name)

Returns all values for a given category option. The result is an associative array with a value for each existing catid

[v2.2] getAllMemberOptions($name)

Returns all values for a given member option. The result is an associative array with a value for each existing memberid

[v3.2] getAllItemOptions($name)

Returns all values for a given item option. The result is an associative array with a value for each existing itemid

[v3.2] getBlogOptionTop($name, $amount = 10, $sort = 'desc')

Returns the top of the values for a given option. The result is an array where every element is an array with a value ('value') for each blogid ('id')

[v3.2] getMemberOptionTop($name, $amount = 10, $sort = 'desc')

Returns the top of the values for a given option. The result is an array where every element is an array with a value ('value') for each memberid ('id') (parameters: see getBlogOptionTop)

[v3.2] getCategoryOptionTop($name, $amount = 10, $sort = 'desc')

Returns the top of the values for a given option. The result is an array where every element is an array with a value ('value') for each categoryid ('id') (parameters: see getBlogOptionTop)

[v3.2] getItemOptionTop($name, $amount = 10, $sort = 'desc')

Returns the top of the values for a given option. The result is an array where every element is an array with a value ('value') for each itemid ('id') (parameters: see getBlogOptionTop)

Database tables

Access to Nucleus tables

Up to v2.0, accessing the nucleus tables was just a matter of performing an SQL query on one of the nucleus_ tables. Since it is possible to use a custom table name in Nucleus versions >2.0, some precautions are needed in plugin development:

As of v3.5, Nucleus is moving toward support for database handlers different from MySQL, such as PDO. Though, this support is beta in version 3.5, plugin developers need to start making their plugins compatible with the new sql_* api used to implement the generic database calls. Essentially, you need onnly replace any mysql_* functions with sql_*, e.g. mysql_fetch_assoc($result) becomes sql_fetch_assoc($result). you must do this for every interaction with the database. Be sure to indicate that you support the SqlApi feature as indicated below, and that you set the minNucleusVersion to 350, like this:
function getMinNucleusVersion( return '350';)

1. Instead of using a fixed tablename like nucleus_item, use the global function sql_table('item') to generate the prefixed tablename
2. Make sure your plugin returns 1 (true) when supportsFeature('SqlTablePrefix') is called on it. If it doesn't, you won't be able to load the plugin on Nucleus versions > 2.0 when a custom prefix has been set (as a precaution)
3. v3.5+. Make sure your plugin returns 1 (true) when supportsFeature('SqlApi') is called on it. If it doesn't, you won't be able to load the plugin on Nucleus versions > 3.5 when a user is using a non-mysql database backend (as a precaution)

Note that the sql_table global function in not available in Nucleus versions up to v2.0. If you use this method and want your plugin to work on Nucleus versions <= 2.0, add the following snippet of code on top of your plugin class:

<?php

// plugin needs to work on Nucleus versions &=2.0 as well
if (!function_exists('sql_table'))
{
	function sql_table($name) {
		return 'nucleus_' . $name;
	}
}

class NP_HelloWorld extends NucleusPlugin {
...
}

?>

Your own tables

If your plugin needs database tables of it's own, you should create them in the install method and remove them in the unInstall method.

Some pointers

• Consider using a table name like nucleus_plug_plugname to avoid conflicts with other plugins. Generate them through sql_table('plug_plugname') to make it work with custom prefixes
• You don't need to make a database connection yourself. You can execute queries using the Nucleus function sql_query() which is a wrapper for the PHP command mysql_query()
• If you do make a database connection yourself, make sure to restore the connection with the Nucleus database afterwards. You can do this by calling sql_connect() at the end of your function. It might also be good to do this from the constructor, to avoid reconnecting constantly. You could then save your link identifier in $this->db and pass that along with every query.
• Also redefine the getTableList() method to make sure your table gets backed up when using the backup function.
• It's a good idea to make the removal of your database tables optional. This will allow your users to temporarily remove your plugin without losing the data. For instance, you may need to make changes to options or database tables requiring that the install() method be run to execute code neccessary to modify existing tables or options. This will require that your users uninstall the old version and then install the new version and losing their data in the process. To make the deletion of your tables optional, you can add an option like this in install():

  $this->createOption('del_uninstall', 'Delete NP_MyPlugin data tables on uninstall?', 'yesno','no');

  and this snippet in uninstall():

  if ($this->getOption('del_uninstall') == 'yes')	{
  	foreach ($this->getTableList() as $table) {
  		sql_query("DROP TABLE $table");
  	}
  }

Plugin Admin Area

As of Nucleus v2.5, plugins can create admin area pages that integrate with the Nucleus admin area. These pages can be accessed either from the plugin admin page, or the quickmenu on the left.

Basics

To provide an admin area, you'll need to take these steps:

1. Create a subdirectory of the plugins directory, and name it pluginname if your plugin is NP_PluginName. Note that the name should be lowercase!
2. In that directory, create a file called index.php, which looks like this:

   <?php
   
   	// if your 'plugin' directory is not in the default location,
   	// edit this variable to point to your site directory
   	// (where config.php is)
   	$strRel = '../../../';
   
   	include($strRel . 'config.php');
   	if (!$member->isLoggedIn())
   		doError('You\'re not logged in.');
   
   	include($DIR_LIBS . 'PLUGINADMIN.php');
   
   	// create the admin area page
   	$oPluginAdmin = new PluginAdmin('PluginName');
   	$oPluginAdmin->start();
   
   	echo '<h2>Plugin Name</h2>';
   
   	echo '<p>Page contents here<p>';
   
   	$oPluginAdmin->end();
   
   ?>

3. Subscribe to the QuickMenu event and add this code in your plugin:

   function event_QuickMenu(&$data) {
   		array_push(
   			$data['options'],
   			array(
   				'title' => 'Plugin Name',
   				'url' => $this->getAdminURL(),
   				'tooltip' => 'Tooltip text'
   			)
   		);
   	}

4. Implement this method in your plugin:

   function hasAdminArea()
   {
   	return 1;
   }

5. Optional. Make the QuickMenu entry optional, and restrict who sees it. The following assumes that an option, of type yesno and called quickmenu, exists in install(). It also will restrict viewing of the QuickMenu entry to super-admins and to blog-admins.

   function event_QuickMenu(&$data) {
       // only show when option enabled
       if ($this->getOption('quickmenu') != 'yes') return;
       global $member;
       if (!$member->isAdmin() && !count($member->getAdminBlogs())) return;
       array_push($data['options'],
         	array('title' => 'PluginName',
          	'url' => $this->getAdminURL(),
          	'tooltip' => 'Administer NP_PluginName'));
   }

Considerations

• Don't just add an entry to the quick menu because it is possible. Imagine having 100 plugins installed, which all add an entry in the menu. This would result in a real mess. So, even if you add an entry in the menu, please consider adding an option (global or member-level) to enable/disable the quick menu entry.
• The $strRel variable in the index.php needs to be adapted manually if the plugins directory is not located in nucleus/plugins/
• Make sure your admin area outputs valid XHTML. If not, the page will be broken in Gecko-based (Mozilla etc) browsers.

The PluginAdmin class

The purpose of the PluginAdmin is to help you. Once created, you can use $oPluginAdmin->plugin to access the instance of your plugin.

Plugin HelpPage

As of Nucleus v3.2 plugins can provide a helppage with an overview of the plugins' functionality, the available skinvars and templatevars, where to get more info,...

The helppage will be accessible from the plugin overview in the admin area.

Basics

To provide a helppage, you'll need take these steps:

1. Create a subdirectory of the plugins directory, and name it pluginname if your plugin is NP_PluginName. Note that the name should be lowercase! This is actually the same directory as for the admin area.
2. In that directory, create a file called help.html. In this file you can document your plugin. This is a good template to start from:

   <h3>Plugin overview</h3>
   
   <p>The only purpose of this plugin is to show how the plugin helppages work</p>
   
   <h3>Installation</h3>
   
   <p>If you can read this you correctly installed the plugin :-)</p>
   
   <h3>SkinVars</h3>
   
   <p>Because this plugin is only a testcase it doesn't has any skinvars/templatevars but suppose it would have:
   
   <ul><li><b><%HelpPageTestCase1%></b>: does something</li>
   <li><b><%HelpPageTestCase1(foobar)%></b>: does something else</li></ul></p>
   
   <h3>Support and Bug reports</h3>
   
   <p>For additional support and/or bug reports please use this forum thread:
   <a href="http://forum.nucleuscms.org/viewtopic.php?t=<TOPIC_ID_GOES_HERE>">
   http://forum.nucleuscms.org/viewtopic.php?t=<TOPIC_ID_GOES_HERE></a></p>
   
   <h3>Version History</h3>
   
   <ul><li>Version 0.1: initial testcaseversion</li>
   <li>Version 0.0: pre-initial version ;-)</li></ul>

3. Return a value larger than 0 for supportsFeature('HelpPage'):

   function supportsFeature($what) {
   	switch($what) {
   	case 'HelpPage':
   		return 1;
   	  default:
   		return 0;
   	}
     }

Plugin Dependency Check

Starting from 3.2, a new plugin interface is added to allow one to declare any dependency on other plugin(s). This is useful for any plugin that requires another plugin to function. It is particularly useful for a plugin to detect broken dependencies that prevent if from functioning properly.

How to write a plugin that utilizes this function

Let's start from a real world example:

NP_PageLinkList depends on NP_BlogWithOffset to function, so we want to make sure a user cannot install NP_PageLinkList whithout first installing NP_BlogWithOffset. With this API, Nucleus offers a way for a plugin to detect any missing dependency before it is installed.

In this case, we want to code into NP_PageLinkList to mark that it requires NP_BlogWithOffset. When the plugin is installed, the core calls a function in the plugin called getPluginDep(). This function returns a list of plugin it requires, and the core will check against all installed plugins and refuse to install the plugin if a dependency is missing.

All we have to do is add this function to NP_PageLinkList:

function getPluginDep() {
	 return array('NP_BlogWithOffset');
}

The plugin dependency check also prevent a plugin from being uninstalled if other plugins have a dependancy on it.

Internationalizing Your Plugin

Internationalization of a plugin allows your plugin to be easily used by people all over the world, people who do not speak the same language as you do. It requires a little additional work for you, but makes translating the output of your plugin as easy as translating a few phrases in a text file. Below is a description of the standard method suggested for use by Nucleus plugins. Thanks to Andy Matsubara for the instructions.

1. Develop your plugin At first, it is easier to develop it in your language. Use of language files is recommended after the plugin becomes stable.
2. Create plugin directory If your plugin name is NP_AbcDef, the plugin directory name is abcdef (always lower case).
3. Create language files Create the language files in the directory of your plugin. The name of the language file must be the same as that of the Nucleus language file name. For example, english.php is for English and default use. japanese-utf8.php for Japanese(UTF-Cool,japanese-euc.php for Japanese(EUC-JP).
4. Define strings Define strings like below in the language file:

   <?php
   define('_ABCDEF_MESSAGENAME',                  'actual strings in the language');
     . . .
   ?>

   You have to define them for all static strings in your plugin. As defined name is used globally in the environment, it is recommended to have a prefix derived from the plugin name(in this case _ABCDEF).
5. Replace static strings Replace static strings in your plugin with the defined names so they will change according to the language file.
6. Create init method Make the init method in the plugin like below

      function init() {
         // include language file for this plugin
         $language = preg_replace( '#[\\|/]#', '', getLanguageName());
         if (file_exists($this->getDirectory().$language.'.php'))
            include_once($this->getDirectory().$language.'.php');
         else
            include_once($this->getDirectory().'english.php');
      }

This logic is same as Nucleus' language file setting.
7. Add language files As English is the default language, it is recommended to have at least the English version.

Formatting your SkinVar output

Some great plugin ideas never receive general use simply because the output generated by the doSkinVar() method is not flexible enough to meet the needs of different skins or URL schemes. Nucleus provides some tools to help you generalize your output in ways that allow each user to fit it to his or her needs.

To create links to Nucleus pages, such as blogs, categories, items, member details, action.php, admin area, or the plugin admin page, use the built in Nucleus functions and global variables described below:

Using a template to format your output is always a good idea. You may want to output an unordered list, but another user may want the same data separated by a simple character, or other unique format. Nucleus provides two ways to create and store the template data. In both examples below, we will be creating a template with 2 variables, <%foo%> and <%bar%>.

1. Using Plugin Options. This method may be the simplest and will work on all versions 3.2 and higher. It's big disadvantage is that plugin options are deleted during an uninstall, so your users may lose customizations during an upgrade of your plugin. Simply create an option in the install() method like the following:

   $this->createOption('my_template', 
   		'Template used to format output of plugin.', 
   		'textarea', 
   		'<li><%foo%> loves <%bar%></li>');

   Then in the doSkinVar() method, determine the values of foo and bar and fill the template like this:

   $mytemplate = $this->getOption('my_template');
   $couples = array(
   			array(
   				'foo'=>'Ricky',
   				'bar'=>'Lucy'),
   			array(
   				'foo'=>'Sid',
   				'bar'=>'Nancy'),
   			array(
   				'foo'=>'Mickey',
   				'bar'=>'Minnie')
   			);
   foreach ($couples as $values) {
   	echo TEMPLATE::fill($mytemplate,$values);
   }

   Now the skinvar for our plugin <%TemplateTest%> will output three lines like this:

   <li>Ricky loves Lucy</li>
   <li>Sid loves Nancy</li>
   <li>Mickey loves Minnie</li>

2. Using Nucleus Core Template System. This method will only work with versions 3.4 and higher. It has the advantage of being using the database-stored template system and can be exported like other template fields. For a full sample plugin using this method, see this thread from the support forum. A summary is given here. First, create the option in install() as in method 1, but now we will use it as a default.

   $this->createOption('my_template', 
   		'Template used to format output of plugin.', 
   		'textarea', 
   		'<li><%foo%> loves <%bar%></li>');

   Then, subscribe to the TemplateExtraFields event like this:

   function getEventList() { return array('TemplateExtraFields'); }

   Then, create a event_TemplateExtraFields method in your plugin, like this:

   function event_TemplateExtraFields(&$data) {
       /* Add an element in the $data['fields'] array using your plugin name as the key 
   	and an associative array containing the field name and field label*/
       /* note that your field names should be lowercase and include the name 
   	of your template as shown below. This will ensure that all template field names are unique. */
       $data['fields']['NP_TemplateTest'] = array(
           'templatetest_body'=>'TemplateTest Body'
       );
   }

   Then, in the doSkinVar() method, you need to retrieve the template and fill it. Note the skinvar now needs to take the template name as a parameter.

   function doSkinVar($skinType,$template = '') {
   	global $blog, $CONF, $manager,$member;
   
   	$template =& $manager->getTemplate($template);
   	if (trim($template['templatetest_body']) == '')
   		$template['templatetest_body'] = $this->getOption('my_template');
   		
   	$couples = array(
   			array(
   				'foo'=>'Ricky',
   				'bar'=>'Lucy'),
   			array(
   				'foo'=>'Sid',
   				'bar'=>'Nancy'),
   			array(
   				'foo'=>'Mickey',
   				'bar'=>'Minnie')
   			);
   	foreach ($couples as $values) {
   		echo TEMPLATE::fill($template['templatetest_body'],$values);
   	}	
   }

   Here, the user needs to go to the template he wants to use and enter the formatting he desires into the TemplateTest Body field. For our purposes, we are using the default/index template. He may enter something like this:

   <li><%foo%> loves <%bar%>!!!</li>

   And using a SkinVar like <%TemplateTest(default/index)%> will output this:

   <li>Ricky loves Lucy!!!</li>
   <li>Sid loves Nancy!!!</li>
   <li>Mickey loves Minnie!!!</li>

3. Formatting Items Using Regular Template. This applies only to versions 3.40 and higher and for plugins which output items. It has the advantage of using the existing Item fields in the core template system, just like the <%blog%> SkinVar does. This requires the use of a method in the BLOG class called readLogFromList() and requires that you input an array of itemids and a template name. If you need to add variables to the template, you can do so using the doTemplateVar() method. Here is an example of a doSkinVar() method that uses this technique. It takes 4 itemids as parameters, then outputs those four items using the default/index template

   function doSkinVar($skinType,$item1 = 0,$item2 = 0,$item3 = 0,$item4 = 0) {
   	global $blog;
   	$highlight = '';
   	$template = 'default/index';
   	$item_array = array($item1,$item2,$item3,$item4);
   	$blog->readLogFromList($item_array, $template);
   }

Additional Reading

As this document is intended to get you started, there are other resources available that offer additional insight.

• Development Wiki
• Nucleus Database Table Structure