Table of Contents »

Plugins

Developing our first plugin, part 2

Difficulty: Easy

Adding more functions and accessing data with our first plugin

In this example we’ll build on our first plugin and introduce a couple of new concepts.

Plugins with multiple functions

A single plugin file can encapsulate any number of related functions. To add more than one function we add an extra segment to the tag. For example, our {exp:hello_world} tag could become {exp:hello_world:display}. The 3rd segment should describe the tag’s function.

Adding the new tag to the plugin is as simple as adding a new method to the plugin’s class that corresponds to the tag’s 3rd segment.

public function display() {
    return "<p>Hello, world</p>";
} 

Note, that we have no longer use the $return_data variable. When using the display method we can simply return the value that we want to display rather than assigning it to the $return_data variable (the $return_data variable is only used because PHP constructors cannot return a value).

We could add more functions to our plugin by adding new methods to our plugin’s class.

Getting data into the plugin

There are 2 ways to provide the plugin with data.

Parameters

Parameters allow you to pass small bits of information to the plugin and are usually used to configure how the plugin works, eg:

{exp:hello_world:display name="Fred"} 

Here’s how we access this data:

public function display() {
    $name = $this->EE->TMPL->fetch_param("name", "world");
    return "<p>Hello, " . $name . "</p>";
} 

We’re using the EE super-object for the first time here. This object gives us access to lots of built-in CodeIgniter and ExpressionEngine functionality, like database access and template parsing. We’ll be using the Template class here.

The fetch_param method takes the tag parameter name as the first parameter, and a second (optional) default value for when the tag parameter is not set. In this case, if the name= parameter is missing from the template tag the default value of world will be used.

Tag data

Tag data is made available by using tags pairs in a template, eg:

{exp:hello_world:display}Bob{/exp:hello_world:display} 

When a tag pair is used, the contents between the opening and closing tags can be used by the plugin. This data is also accessed using the Template class:

public function display() {
    $tagdata = $this->EE->TMPL->tagdata;
    return "<p>Hello, " . $tagdata . "</p>";
} 

In this case, we get the data using the $this->EE->TMPL->tagdata property.

Summary

We’ve quickly seen how to make a plugin with a number of different functions, and we’ve fetched data from the template to use within the plugin.

We’ve also used the EE super-object for the first time and accessed the Template class to easily data into our add-on.

 

Comments (2)

Developing our first plugin

Difficulty: Easy

How to build a simple plugin.

Let’s start with a simple plugin that displays “Hello, world”.

Giving the plugin a name

The first decision when creating a plugin is to give it a short name. This will define:

A sensible short name for our plugin is hello_world, so we’ll create a folder in system/expressionengine/third_party called hello_world which contains the file pi.hello_world.php.

Folder structure for the plugin

Creating the plugin class

In the file pi.hello_world.php we’ll add the following code:

<?php  if ( ! defined('BASEPATH')) exit('No direct script access allowed');

$plugin_info = array(
    'pi_name' => 'Hello World',
    'pi_version' => '1.0',
    'pi_author' => 'EE Recipes',
    'pi_author_url' => 'http://ee-recipes.com/',
    'pi_description'=> 'A dummy plugin',
    'pi_usage' => Hello_world::usage()
);

class Hello_world {

    public $return_data;
    
    public function __construct()
    {
        $this->EE =& get_instance();
        $this->return_data = "<p>Hello, world</p>";
    }
    
    public static function usage()
    {
        ob_start();
?>
Documentation goes here...
<?php
        $buffer = ob_get_contents();
        ob_end_clean();
        return $buffer;
    }
}

/* End of file pi.hello_world.php */
/* Location: /system/expressionengine/third_party/hello_world/pi.hello_world.php */ 

We’ll go through this file in more detail in a moment, but the first thing to notice is that the file contains a single class called Hello_world, the short name with the first letter capitalised, and the class has a constructor and one other method usage.

One step at a time

Firstly, the $plugin_info array sets up some useful information. None of this is used by the plugin in a template, but is used when viewing the plugin in the Control Panel.

$plugin_info = array(
    'pi_name' => 'Hello World',
    'pi_version' => '1.0',
    'pi_author' => 'EE Recipes',
    'pi_author_url' => 'http://ee-recipes.com/',
    'pi_description'=> 'A dummy plugin',
    'pi_usage' => Hello_world::usage()
); 

Note, the pi_usage key points the the usage method of the class - we’ll come to that in a minute.

Next, we start the class and define the $return_data property. This is used to return the data that we want to display in the template.

The constructor function importantly creates a local reference to the ExpressionEngine super-object.

$this->EE =& get_instance(); 

This object allows us to access EE’s numerous built-in methods (eg, to access the database) and you’ll find this line in all EE add-ons.

The constructor then sets the $return_data property to the text we want to display.

$this->return_data = "<p>Hello, world</p>"; 

Finishing touches

And that’s it. That’s all a plugin needs, but you’ll usually also include a usage method at a minimum. This method returns a string and provides the plugin with some brief instructions that will display in the plugin’s Control Panel page.

The plugin details page

And we’re done!

Now, if we include the tag {exp:hello_world} in a template, it will display “Hello, world” in its place

This is obviously a very simple plugin but it shows how easy it is to create an add-on. We’ll build on the basic ideas from this introduction to create more complex plugins.

 

Add a comment

The different types of add-on, part 1 - plugins

What is a plugin and what can they do?

Plugins are the simplest type of add-on to create and allow you to add new front-end template tags. These tags can be used to do all manner of powerful things - EllisLab themselves have released plugins to modify displayed data, read and display RSS feeds from external sites, and even mimic cron jobs.

Plugins can be used to keep PHP out of templates, which is often beneficial from a speed point of view

Plugins are the easiest add-on to develop as they are a single PHP file and require no installation other than placing in the appropriate folder.

Complexity: simple
Area of use: within templates

 

Add a comment

ExpressionEngine add-ons

A quick summary of the available EE2 add-ons.

ExpressionEngine 2 has six types of add-on and the differences between them can be confusing at first.

The original four types - available since EE1 - are:

ExpressionEngine 2 introduced two new types:

Each type has a different level of complexity and except in the case of plugins and modules their own distinct areas of usage.

I’ll introduce each type of add-on separately.

Permalink