Made of Everything You're Not

In Expression Engine Escaping Madness I laid out an issue I was experiencing with a client site. The issue was that there didn't appear to be a method available to escape Expression Engine markup when it is mixed with php so there is a definite risk of parse errors using that technique (it's not a security issue or anything; I want to be clear on that). This made me nervous enough that I couldn't let it go and kept thinking about how to get around the issue. The answer: write an Expression Engine plugin. Of course this meant I had to actually learn how to write an Expression Engine plugin first. Here are my notes

First though credit where it's due: for this example I used the number_format plugin as a base so a lot of credit goes to Robert Wallis for the nicely written plugin I'm basically leaching from:)

An Expression Engine plugin is essentially a php class with at least one method that translates into an Expression Engine tag and used inside of Expression Engine templates (I don't think they can be used inside of entries directly though I haven't confirmed this). They are best left for small tasks though because they can't have an administrative backend or integration with the Expression Engine l10n stuff or form processing or any manageable settings. No fun stuff for plugins...

Like most platforms there's a few conventions that have to be followed but, also like most platforms, they aren't too troublesome to work with. It should be noted that the syntax for the class uses the php4 syntax so dumb yourself down accordingly.

For example our plugin class will look like:

<?php
class Add_Slashes
{
	function Add_Slashes()
	{
 
        }
}

And the plugin will be executed with the below Expression Engine template tag:

{exp:add_slashes}O'Reilly{/exp:add_slashes}

Now, it's possible to create template tags that aren't done in pairs but for this example I'm going to stick with pairs. In case it wasn't obvious, if you wanted to have a plugin that has more than a single method you would call that method like:

{exp:add_slashes:somethingelse}O'Reilly{/exp:add_slashes:somethingelse}

So that's the basic syntax. The next thing that needs to be done is that a file has to be created inside the "/system/plugin/" folder. Note that I'm using the default name for that folder (system) so if you renamed it during the installation process use that instead. The file name must be lower case the same as the class name and it must have pi. as the prefix, and begin with the second segment of the tag. So, with our example plugin, the plugin name would be: pi.add_slashes.php. Simple enough. Once the file is saved to the location the plugin is installed. That's how Expression Engine rolls.

Now we have a working plugin in theory but if you go into the plugin manager you'll see an error about a missing variable as well as a distorted view of the page. We're missing something; the $plugin_info array.

Every Expression Engine plugin should have a variable outside of the class called $plugin_info. For our example it should look like the below:

<?php
$plugin_info = array(
	'pi_name'        => 'Add Slashes',
	'pi_version'      => '1.0',
	'pi_author'       => 'Eric Lamb',
	'pi_author_url'  => 'http://blog.ericlamb.net/',
	'pi_description' => 'Exposes PHP\'s <a href="http://php.net/manual/en/function.addslashes.php">addslashes()</a> function via EE tags.',
	'pi_usage'        => Add_Slashes::usage()
);
?>

Obviously, the above lists all the details about the plugin for display in the plugin administration module:

You may have noticed the pi_usage key in the array; this method is recommended by the Expression Engine Developer Center for describing the usage of a plugin. Inside the plugin create a method called usage() and just return the instructions. Those instructions will be used on the plugin description page:

Using all of the above the completed plugin is below:

<?php
$plugin_info = array(
	'pi_name'        => 'Add Slashes',
	'pi_version'      => '1.0',
	'pi_author'       => 'Eric Lamb',
	'pi_author_url'  => 'http://blog.ericlamb.net/',
	'pi_description' => 'Exposes PHP\'s <a href="http://php.net/manual/en/function.addslashes.php">addslashes()</a> function via EE tags.',
	'pi_usage'        => Add_Slashes::usage()
);
 
class Add_Slashes
{
	function Add_Slashes()
	{
		global $TMPL;
		$this->return_data = addslashes($TMPL->tagdata);
        } 
 
	function usage()
	{
		return "This is really just a wrapper for PHP's add_slashes function:
http://php.net/manual/en/function.addslashes.php
 
&#123;exp:add_slashes&#125;
O'Reilly
&#123;/exp:add_slashes&#125;
returns: O\'Reilly
 
";
	} 
 
}

Now, this example was used using Expression Engine 1.6.9 so the process might not work for the upcoming 2.0 (I haven't looked into that version just yet). It also doesn't look like EllisLabs is accepting any new submissions to their plugin library so if you're hoping to distribute your plugin prepare to do it solo and without any help from them.

Still, an easy enough process that any custom functionality you may need for an Expression Engine site should be trivial to achieve.

UPDATE February 21, 2011
I completely forgot to include any info on customization through passing parameters. Note: this is totally cribbed from the ExpressionEngine forums.

{exp:add_slashes return="FALSE"}
O'Reilly
{/exp:add_slashes}

Doing the above will create a variable within the plugin called "return" which can be accessed like:

<?php
global $TMPL;
$return = $TMPL->fetch_param('return');
?>

While working on Wp-hResume (a neat plugin for adding any hResume encoded resume to a WordPress site) I needed to make a decision. The strategy I was working on hinged on the choice between either using brute force regular expressions to parse the profile page for a single site (like the competition)  or to write the missing hResume profile for the hKit Microformat Framework.

The way I saw it, with regular expressions I could only build a plugin that would only work with a single site; whereas with an hKit profile the plugin could, in theory, work with any hResume encoded site. So, clearly, an hKit profile was the best option.

The only problem was that there isn't any documentation on how to actually create a profile for hKit. I don't want to go into detail on it, and to be honest I don't really remember all the details so suffice it to say that brute forcing this thing sucked. Donkey balls. It took forever and the steps needed to build a profile used a methodology I wasn't familiar with. But, after a long night of tequila I did end up putting it all together though and it works pretty nicely.

First though, here's how hKit works for pulling in a microformatted URL:

<?php
include('hkit.class.php');
$hKit = new hKit;
$result = $hKit->getByURL('hcard', 'http://microformats.org/');
?>

Pretty obvious stuff; give it a URL, set the type of encoding expected (this time it's hcard) and it gives back an array with all the goodies.

To work with the new profile you have to place the profile file in the same directory as hkit.class.php. You can download the profile along with the latest version of hKit here.

The concept is the same with the new profile:

<?php
include('hkit.class.php');
$h = new hKit;
$url = 'http://www.linkedin.com/in/mithra62';
$h->tidy_mode = 'proxy'; // 'proxy', 'exec', 'php' or 'none'
$result = $h->getByURL('hresume', $url);
print_r($result, 1);
?>

The above will pull my hResume encoded info from my LinkedIn profile. Same as the original hcard example. Easy like your sister.

Now go forth and start parsing hresume encoded URLs