I recently had a project come up that could have gone one of two ways from a  strategic design stand point; either as a straight up script custom built for the occasion or, time warranting, I could build an extension for ExpressionEngine. As I’d already looked into writing an ExpressionEngine plugin the idea of writing an extension was pretty enticing regardless of the added time costs I would have to swallow (can’t bill the client for my fun now can I?).

The only problem is that the project in question was built on ExpressionEngine 1.6.7 and ExpressionEngine, having recently released 2.0 with all new bells and whistles and ways of doing things, updated their documentation as well. I couldn’t find any documentation for writing extensions for 1.6x though there’s a really nice help center for 2.0. A little advice third party developers; don’t just remove documentation and replace it with the new stuff because, as shocking as this may sound, people still use the old stuff.

To ExpressionEngine an extension is a script built to modify how ExpressionEngine works as opposed to adding additional functionality like a plugin would do. For example, a plugin would be good for adding a drop in template tag while an extension would be good for changing how ExpressionEngine parses all template tags. If you’re used to the WordPress development paradigm think of extensions as hook filters in Wordpress plugins.

Those aren’t the only distinction though; extensions can also have a settings section, language files and database tables too so you’re really going  to need at least an extension for any deep functionality or customizations (there are also ExpressionEngine modules and expansions but that’s for another day).

Codewise, ExpressionEngine extensions are pretty similar to plugins insofar as structure and elements. At the core an extension is a PHP class that follows the same naming structure for both the class and the file as a plugin except the prefix changes and where you store the file. ExpressionEngine extensions should be named with a prefix of “ext.” and the class name, include a couple class variables for information about the extension, a couple methods to activate, deactivate and remove the extension and, ideally, a method to be called when the “hook” is executed.

As an example let’s put together an extension stub for a demonstration of how things should be setup

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

<?php
class Pissoff_client
{
	/**
	 * Name of the extension
	 * @var string
	 */
	public $name = 'Enrage The Client';
 
	/**
	 * Version of the extension
	 * @var string
	 */
	public $version = '1.0';
 
	/**
	 * The description of the extension
	 * @var string
	 */
	public $description = 'Replaces every instance of one word with another from all entries';
 
	/**
	 * Flag for whether this extension has settings
	 * @var string
	 */
	public $settings_exist = 'n';
 
	/**
	 * URL to the documentation for the extension
	 * @var stirng
	 */
	public $docs_url = 'http://url_to_documentation.com';
 
	/**
	 * The available settings for the extension
	 * @var array
	 */
	public $settings = array();
 
	/**
	 * Constructor
	 *
	 * @param 	mixed	Settings array or empty string if none exist.
	 */
	function Pissoff_client($settings = '')
	{
		$this->settings = $settings;
	}
 
	/**
	 * Activate Extension
	 *
	 * This function enters the extension into the exp_extensions table
	 *
	 * @see http://codeigniter.com/user_guide/database/index.html for
	 * more information on the db class.
	 *
	 * @return void
	 */
	function activate_extension()
	{
		global $DB;
 
		// default settings
		$settings =	array();
		$hook = array(
				'extension_id'	=> '',
				'class'			=> __CLASS__,
				'method'		=> 'run',
				'hook'			=> 'hook_to_process_extension_on',
				'settings'		=> serialize($settings),
				'priority'		=> 1,
				'version'		=> $this->version,
				'enabled'		=> 'y'
		);
 
		$DB->query($DB->insert_string('exp_extensions',	$hook));
	}
 
	/**
	 * Update Extension
	 *
	 * This function performs any necessary db updates when the extension
	 * page is visited
	 *
	 * @return 	mixed	void on update / false if none
	 */
	function update_extension($current = '')
	{
		global $DB, $EXT;
 
		if ($current < $this->version)
		{
			$query = $DB->query("SELECT settings FROM exp_extensions WHERE class = '".$DB->escape_str(__CLASS__)."'");
 
			$this->settings = unserialize($query->row);
			$DB->query($DB->update_string('exp_extensions', array('settings' => serialize($this->settings), 'version' => $this->version), array('class' => __CLASS__)));
		}
 
		return TRUE;
	}
 
	/**
	 * Disable Extension
	 *
	 * This method removes information from the exp_extensions table
	 *
	 * @return void
	 */
	function disable_extension()
	{
		global $DB;
		$DB->query("DELETE FROM exp_extensions WHERE class = '".__CLASS__."'");
	}
 
	/**
	 * Method to execute when hook is called
	 * @param mixed $data
	 */
	public function run($data)
	{
 
		//process
	}
}

Most of the above should be self explanatory but just in case what’s going on is that most of the class variables are used for extension details and there are 3 methods for activating, deactivating and removing the extension. The methods for activation management are important, especially the activation method “activate_extension” which contains the details about the extension including the hook to execute on along with the method name to execute when the hook is called. In the above example, the extension will execute the method “run” when the hook “hook_to_process_extension_on” is called. Thankfully, ExpressionEngine hasn’t done away with the list of hooks available in the 1.x branch.

Obviously, the above extension is pretty useless, what with not doing anything, but that’s all you’re gonna need to have the extension listed in the Extension Manager. To further personalize and customize (huh… I’m a poet) the details of your extension you can add settings and, if you want people to have the ability to change those settings, you can add a settings page by.

To add a settings page to your extension things get a little complicated at first but it’s not so bad. All you have to do is set the class variable $settings_exist to “y”, create a new method called “settings()” that EE uses and modify your extension language file (should be created inside the “lang” directory using the convention of “lang.extension_name”). The settings() function should contain an associative array with the key being the name of the setting and any default value for that setting like the below:

<?php
function settings()
{
	$settings = array();
	$settings		= '';
	$settings	= 'this is the default value';
	return $settings;
}

Using the above will simply display a form with 2 text boxes for input. If no value is provided for the second item then there’ll be a default used. Simple. But, if you want to use, say, radio buttons or select boxes you have to make a couple modifications like the below:

<?php
function settings()
{
	$settings = array();
 
	$settings = array('t', 'Default!!');
	$settings = array('r', array('nothing' => "Nothing", 'something' => "Something"), 'something');
	return $settings;
}

The above will create a new setting form with a textarea for the first option and a radio fieldgroup for the second. Make sure you add the radio option text to your language file though; it won’t do that automatically. Also, you’re not locked into just radio and textareas; you can also have select boxes (s) and multi-select boxes (ms) by updating the relevant array key.