====== Plugins / Advanced Examples ======


Plugins can be much more complex, and can grow to include a large set of many different functions to accomplish various tasks. This article covers how to pass values to your plugin functions, control runtime order, and most importantly, modify data supplied by an anchor.

====== Passing values to a plugin function ======

Sometimes your plugin functions will accept certain parameters, so you will need a way to pass values to them. Plugins are free to run code outside of functions specifically for this reason, so you can do things like retrieve data from the database on runtime.

Here is an example:
<code php>
<?php
	// Some variable
	$title= "Mikael's Clock";
	$time= time();

	// Hooks
	hook( "anchor_name", "myPlugin", array( $title, $time ) );

	function myPlugin( $title, $time )
	{
		echo $title . ": " . date( "h:i", $time );
	}
?>
</code>

====== Controlling runtime order ======

Some plugins need to be called before or after others, so there is an option to define the "hierarchy" of a plugin. Simply give an integer value, where 1 is run first. Default order is the order plugins are read into the system, which is defined by the file/folder order of your server (normally alphabetical).

<code php>
<?php
	hook( "anchor_name", "myPlugin", "", 3 );
?>
</code>

====== Modifying data supplied by an anchor ======

Sometimes anchors are put into place in order to allow customization of data coming in or out of the system. This can be used to control everything from JavaScript objects, as in the slideshow display type, or the site title used in the <title> tag.

For this example, we will modify the site title to include the name of the current page.

<code php>
<?php
	hook( "siteTitle", "custom_site_title" );

	function custom_site_title( $title )
	{
		$title.= " / " . pageName();
		return $title;
	}
?>
</code>

When modifying data, the plugin function must always return a value.

====== Defining anchors within a plugin ======

Plugins can create anchors for other plugins to hook into, greatly extending functionality. Defining an anchor is simple:

<code php>
<?php
	// Define anchor
	define_anchor( "myAnchor" );

	function my_plugin()
	{
		// Do cool stuff
		// ...

		// call anchor
		call_anchor( "myAnchor" );
	}
?>
</code>

====== Defining anchors that modify data ======

<code php>
<?php 
	// First define the anchor 
	define_anchor( "formatTitle" ); 
 
	function my_plugin()
	{
		// $title could be a value grabbed from the database, for example 
		$title= "Line's Music Blog"; 
		$title= call_anchor( "formatTitle", $title ); 
	}
?>
</code>

Now, if one were to create a plugin that modified this title in some way, it would look like this:

<code php>
<?php 
	hook( "formatTitle", "myFormatting" ); 
 
	function myFormatting( $title ) 
	{ 
		return '<h1>' . $title . '</h1>'; 
	} 
?>
</code>

===== Passing multiple values  =====

Anchors can also pass multiple values. To do so, supply an array instead of a single value.

<code php>
<?php
	$title= call_anchor( "formatTitle", array( 'title' => $title, 'name' => $name) ); 
?>
</code>