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:

the template tag (eg, {exp:short_name})
the plugin’s folder name (eg, short_name)
the name of the plugin file (eg, short_name/pi.short_name.php)

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.

Articles