Jump to Content

Objective HTML

Postmaster

The definitive email solution for ExpressionEngine

Utilities API

Overview

Utilities allow developers to add additional template tags without hacking the core. The create a new Postmaster utility, you need to create a Delegate - which is a new type of API for ExpressionEngine. Delegates allow add-on developer an extendible base to build EE tags. Once a module has been built on top of a delagate architecture, other developers can add new tag without hacking the core.

So why it is a utility, but yet it is called a delegate?

To the end user, the concept of a delegate is pretty hard to grasp. The term Utility is really just a more friendly way of sayings Delegate. However, the Delegate API is not exlusive to Postmaster, therefore this specific implementation has been named Utilities.

Delegate Tag Breakdown

// Delegate Syntax
{exp:module_name:delegate_name:method}

// An actual Delegate
{exp:postmaster:campaign:subscribe}

// Prior to EE 2.5 the delegate method in the 3rd segment
{exp:postmaster:delegate:campaign:subscribe}

A delegate tag functions just like EE. It has four segments, but works the same as a tag with 2 or 3. However, delegates require EE 2.5+ so a 5 segment tag is required to make it work for older version.

Delegates Directory
/system/expressionengine/third_party/postmaster/delegates
Class Suffix
_postmaster_delegate

Delegate Class


class Your_delegate_name_postmaster_delegate extends Base_delegate {
	
	public function __construct()
	{
		parent::__construct();
	}
	
	public function your_method_name()
	{
		$params = array(
			'abc' => $this->param('abc')
		);
		
		// Do something
	}	
}

Delegate Tag


	{exp:postmaster:your_delagate_name:your_method_name abc="123"}

Parameters

EE
The global EE instance object
suffix
The delegate class suffix
name
The delegate name

Methods

These methods are available in the delegate class since you inherited the Base_delegate.

get_delegate($name)

Get a delegate object by passing the delegate name as a string.

$name
Delegate name as a string
Return

(object) A delegate object.

get_delegates($name = FALSE, $directory = '../delegates')

Get all the delegates in any given directory.

$name
Delegate name as a string
$directory
Directory path of the delegates/dd>
Return

(array) An array of delegate objects.

json($data)

Output a JSON response

$data
Mixed datatype to be encoded to a JSON string
Return

(JSON) JSON Object

load($data)

Load a delegate object

$name
Delegate name as a string
Return

(JSON) JSON Object

param($param, $default = FALSE, $boolean = FALSE, $required = FALSE)

Fetch a template tag parameter

$param
Parameter name as a string
$default
The default parameter value, which is FALSE by default.
$boolean
Is the parameter a boolean value
$require
Is the parameter required
Return

(string) Parameter value

parse($vars, $tagdata = FALSE)

Parse an array of variable and return a string

$vars
An array of variables to be parsed
$tagdata
This is the string to parse, if FALSE the template tagdata is used.
Return

(string) A parsed string

show_error($error)

Output an error string

$error
An error string to output
Return
NULL

tag_part($param, $default = FALSE, $boolean = FALSE)

Fetch a template tag parameter

$param
Tagparam name as a string
$default
The default tagpart value, which is FALSE by default.
$boolean
Is the tagpart a boolean value
Return

(string) Parameter value