ExpressionEngine, Tutorials

Adventures in Updating an ExpressionEngine Plugin from 1.6.8 to 2.0

January 21, 2010
by Jacob Russell

You’re developing a site in ExpressionEngine 2.0 and need a plugin that only has a 1.6.8 version. You could wait for the developer to update it, which could take months and might never happen. On the other hand if you’re willing to get your hands dirty you can try updating it yourself. We’ll tell you how, and it’s not as hard as you think!

ExpressionEngine 2 has been out for a month and a half now, but much of the development talk in the community still centers around ExpressionEngine 1.6.8.  In fact, a recent devot:ee poll shows that 36.2% of you expect to wait at least 6 months before even starting to develop sites in ExpressionEngine 2.  A further 20.8% are waiting for ExpressionEngine 2.1, which could be equally as long a wait.  That’s over half of all developers in the poll who aren’t even thinking about developing for ExpressionEngine 2 yet.

The way I see it, there’s two major reasons for that number.  The first reason is that developers are waiting for ExpressionEngine 2 to mature more before releasing it in any sort of production environment.  That factor is largely out of our control, it’s entirely up to EllisLab, so we won’t address it here.  The other reason is the availability, or lack thereof, of popular and important add-ons.  Among the top 50 favorite add-ons here on devot:ee, only four are currently available for ExpressionEngine 2, while another twelve have announced timelines.  That’s a lot of functionality that developers have come to count on that’s completely unavailable in ExpressionEngine 2.

While developing a site in ExpressionEngine 2 recently, I ran into this problem myself.  I wanted to add ‘tweet this’ functionality to channel entries, and in fact several add-ons exist to do just that in ExpressionEngine 1.6.8.  Rather than just wait for one of these add-ons to be updated by its developer I decided to take a shot at updating it myself, and it turns out that it’s not that hard.

The Plugin

alt text

The plugin we’ll be walking through updating is Short’n Tweet, originally developed by Eric Barnes and later extensively updated by our own Ryan Masuga.  As plugins go it’s a fairly simple one, clocking in at 263 lines including its header and fairly liberal commenting.  It also doesn’t do any database interaction, which makes updating less complicated.

The Resources

The Process

Out With the Weblog, in With the Channel

The first and most obvious change we need to make is using ‘channel’ instead of ‘weblog’  anywhere it’s referenced.  In the case of Short’n Tweet it’s only used in the usage function, which displays usage information for the plugin in the control panel.  It’s not a vital change as far as functionality goes, but our end users will be reading these instructions, so we want to make sure they’re correct.  In the example below you can see the change of term.  I’ve left the old version intact to show you what it looks like, but in practice you’d just want to change the word.


{exp:shortn_tweet title="{title}" url="{title_permalink=blog/entry}"}
//Old Format
{exp:shortn_tweet title="{title}" url="{url_title_path=weblog/item}" short_url=""}

//New Format
{exp:shortn_tweet title="{title}" url="{url_title_path=channel/item}" short_url=""}
  <li><a href="{twt:twitter_url}{twt:title} {twt:title_url} (via @masuga)">Tweet this thang</a></li>

The Super Object

The biggest functional difference between 1.6.8 and 2.0 as far as plugins are concerned is the switch from global variables and methods to the super object.  Most of your calls will still work the same, but they’ll be formatted differently and interact with ExpressionEngine in a new way.  These changes first show up in the plugin constructor function, which is the first function in the plugin class.  In our case it looks like this:

class Shortn_tweet {
	var $return_data = "";
	// --------------------------------------------------------------------
	* Constructor
	* Get the tweet text
	function Shortn_tweet()
		global $TMPL, $FNS;

To update ours we’ll get rid of our globals (don’t worry, we’ll be able to reference them differently later in the code) and add the super object reference:

class Shortn_tweet {
	var $return_data = "";
	// --------------------------------------------------------------------
	* Constructor
	* Get the tweet text
	function Shortn_tweet()
		$this->EE =& get_instance();

Referencing the Super Object

Using the super object also means that we’ll need to change a lot of references in our code.  Remember that $TMPL global we got rid of?  Originally Short’n Tweet referenced that global to get template information from ExpressionEngine.  The good news is that there’s no functional difference between the way it used to work and the way it does now, at least as far as we’re concerned.  All we have to change is the syntax.  In fact, the very next line in the plugin needs to change.

$tagdata = $TMPL->tagdata;

After the change $TMPL becomes:

$tagdata = $this->EE->TMPL->tagdata;

Now that we know what we’re looking for, changing the global over is a simple matter of a find and replace.  In Short’n Tweet a quick search turns up an additional five instances of $TMPL, and we’ll just overwrite those with $this->EE->TMPL.  What makes this easy for those of us who don’t dream in code is that you don’t need to understand what each of these calls even does in order to update it.  All we need to know is how the syntax should look.

We also need to reference the super object with our functions, which in ExpressionEngine 1.6.8 was designated with the global $FNS.  That was the other variable originally created by the plugin in it’s globals section.  EllisLab documents this change on the Syntax Guidelines page here.  When we apply it it looks like this:

if ($tagdata != '')
	$f = array(LD.'twt:title'.RD, LD.'twt:title_url'.RD, LD.'twt:twitter_url'.RD, LD.'twt:twitter_full_url'.RD);
	$r = array($title, $title_url, $twitter_url, $twitter_full_url);
	$c = array('twt:title' => $title, 'twt:title_url' => $title_url, 'twt:twitter_url' => $twitter_url, 'twt:twitter_full_url' => $twitter_full_url);
	//$this->return_data = str_replace($f, $r, $FNS->prep_conditionals($tagdata, $c));
	$this->return_data = str_replace($f, $r, $this->EE->functions->prep_conditionals($tagdata, $c));

In the case of Short’n Tweet, that’s all we need to change as far as syntax.  If you’re working on a different plugin, you’ll want to look through the rest of the syntax changes and update any that are relevant to your plugin.

Redundant Functions

While looking through general syntax changes I discovered that the str_replace SLASH function in the plugin was now redundant. Per the docs:

The SLASH constant has been removed from the template parser, and forward slashes are no longer converted to entities.

Implementing that change is simple matter of commenting out the line in question.

// Format URL //
$title_url = $this->EE->TMPL->fetch_param('url');
// Rendered unneccesary by EE2, commenting out.
//$title_url = str_replace(SLASH, '/', $title_url); // fix any encoded slashes

Folder Structure

One of the nicer changes in ExpressionEngine 2 is the switch from separate plugin, module and extension folders to a single third-party add-on folder that holds ‘packages.’  While this won’t mean much to us here, with larger add-ons it means that all the files will sit in one place, instead of being split between a number of separate folders.  In our case it means that we will be placing pi.shortn_tweet.php in a folder called shortn_tweet.  Then to install the plugin all we need to do is place that folder in /system/expressionengine/third_party.

The Result

alt text

Once the add-on package has been placed in the third party folder of an ExpressionEngine 2 install you’re done.  Assuming nothing was missed, it will show up in the control panel and work just like it did in 1.6.8.  That’s it, you’re good to go!

Well, you’re done if you’re updating this specific plugin.  If you’re working with a different plugin (or likely a simple module or extension), the changes you will need to make will differ to some degree.  For the most part however the only difference in migrating to 2.0 will be what syntax you’re updating.  Maybe the plugin you need has email functions, uses libraries, or accesses the database and you’ll need update that code instead.  The point is that while the specific needs of each plugin will change, the actual updating is a fairly straightforward process for simple plugins.

So what are you waiting for?  Go forth and update!  Oh, and while you’re at it let the developer know so they can roll it into the released add-on for the rest of us!


Philip 01.21.10

Re-developing addons is a great way for beginners to pick up EE addon development; and it’s surprisingly easy. I’ve ported several addons (plugins) over to EE2.0 and it’s taken very little time. I’d be interested to see an article more related to Modules and Extensions :)

nevsie 01.21.10


i second the above and would also like to see some quick guides to plugs, mods, extens, etc. or even updating your developing with fieldframe extension article to the new 2.0 version and what differences there are!

Jacob Russell 01.21.10

Jacob Russell

I would love that too! :)  I can’t make promises on more complicated updating articles, since I’m very much a beginner when it comes to EE Add-on Development.  This article was as much a learning opportunity for me as it was a way to introduce other newbie add-on devs to how easy the upgrade is.  I definitely like the idea of taking the concept of this article deeper with other add-on types though, so we’ll talk things through here and see what we can come up with.

Philip 01.21.10

What does Ryan do all day? Other then play with Gowalla that is.

Jacob Russell 01.21.10

Jacob Russell

Mostly that and drink from his travel mug.  He swears it’s filled with coffee, but I’ve never seen coffee poured from a flask…

CreateSean 01.22.10

Great article – wish there was a way to add this to favorites same as add-on favoriting.

Jacob Russell 01.22.10

Jacob Russell

Good point, you might see that show up at some point in the not-so-distant future. :)

Matt Stein 02.06.10

Helpful, direct, and well-timed article! This was enough to get me started porting over the plugins I’ve realized I depend on! In the meantime if anybody can whip up another FreeForm please let me know ;)

You must be registered member to comment. If you're already a member, log in now, and if not go register (it's free and easy!).