Starting from the basics of how to create common add-on types, we’ll look at a range of techniques to harness the power of EE’s (and CodeIgniter’s) built-in classes and functions to build add-ons that enhance your own EE sites and/or that can be published for the community.

We’ll focus on:

• how to build different types of add-on
• useful classes and functions available within EE and CI
• the database structure and how to retrieve and modify data
• EE add-on ‘design patterns’ — conventions that you should follow when confronted with common situations

If there are any other aspects of add-on development that you want see let me know.

The site is aimed at PHP developers who use EE and want to start developing their own add-ons, but there should be enough to keep experienced add-on developers interested (in fact, I’d welcome any suggestions of improvements). This site won’t teach you how to build websites with ExpressionEngine — there are better resources available for that.

To keep the frequency of posts as high as possible, articles will initially be released in a blog format, as-and-when they are ready, and larger topics will be split into several articles to keep the subject matter more manageable. When there is a little more content I’ll organise the site into a more useful structure (and fill in any gaps).

Thanks for your interest. Any suggestions will be greatly received.

- Andrew Weaver (brandnewbox.co.uk)

It was useful for the summary tag to be able to run within a channel entries tag as this would be how we would often want to use it to (ie, to display lists of auctions).

However, it is good practise in ExpressionEngine not to nest tags inside others if possible.

Nested tags can lead to you inadvertently using a large number of database queries. A tag that is included inside another tag that loops over a number of iterations will be run multiple times. Depending on the complexity of the internal tag this could be a very bad thing.

From a template processing point of view it can also lead to variable scope clashes if both tags use the same variable. EE automatically generates some variables if you use the $this->EE->TMPL->parse_variables function, such as {count}, {total_results} and {switch} and if you nest tags then it is impossible to control which version of the variable will be used (it will always be the value from the outer tag).

So where possible it is best to design tags that can be used on their own. With this in mind the history tag will be designed to used outside the channel entries tag.

The history tag will be used on single entry pages, that is, pages where only a single auction is displayed rather than a list of them. These pages will be identified by having either the auction entry’s entry id or url title in the page’s URL.

We can then use the segment variables to identify which auction’s history to display. To keep the tag flexible we’ll make it optional whether we use entry id or url title.

To get the auction’s entry_id from the entry’s url_title, we’ll need to join the exp_channel_titles table.

We also want to include some details about the bidder, so we need to join the members table to fetch the user’s screen name.

The $query->result_array() function returns an array of results which is exactly how $this->EE->TMPL->parse_variables likes it, so it easy to produce the final results of.

This leaves us with the final history function of:

The purpose of this tag was to display the auction’s current bid price and the total number of bids.

So far we had got:

We were hard-coding the current_bid and total_bids values in the $data array as (at that stage) the auction database was empty.

All we need to do is to replace the ‘dummy’ values in the $data array with the correct values from the auction database table:

Here we’ve used the Active Record class to build the SQL to fetch the data:

One thing to note is that the database functions are intelligent enough to add (or replace) the database prefix that you configured when you installed EE. For example, my auction database table is actually called exp_auction. I could use $this->EE->db->get( "auction" ) or $this->EE->db->get( "exp_auction" ) to access it. Equally, if I used a different prefix (you can choose to do this when you install EE), the database functions will use that value. Even if you use $this->EE->db->get( "exp_auction" ) and you have chosen to use a different prefix, EE will use the appropriate table name.

We then test to see if any rows have been returned. If not, either the auction’s entry id does not exist or no bids have been placed yet. In either case, we’ll display the price and number of bids as zero.

If the SQL query does return a row, we’ll use that. The $query->row_array() will return the next (in this case, first) row’s result as an array, with columns mapped to array elements, eg:

Summary

So we now have the {exp:auction:summary} tag working. We are now able to display an auction item with details of the current bidding situation, with a working form that allows visitors to place their own bid.

In the previous article, we set up the place_bid() function to receive the form submission. To check place_bids() is actually getting the form data, we’ll add a line to display any POST-ed data:

If we submit a bid for one our auctions we should now see:

We can see that the inputs entry_id and bid_amount that we defined in the form are there, along with a few others. The ACT value denotes the id of the action that we set up previously (ie, the place_bids function) and ExpressionEngine has added the XID and site_id values. The site_id is used to determine which site is being used when Multiple Site Manager is installed (by default it uses the value ‘1’). We’ll explain the XID value in another part.

Fetching the data

While we can use the $_POST array to get the submitted values, EE provides a better alternative using the Input class.

The class is loaded by EE and automatically cleans up any input data (eg, POST/GET/COOKIE) provided. It also provides a handful of helper functions.

The $this->EE->input->post() function is a function to access data POSTed to the system by a form, eg:

will look for entry_id element of the $_POST array and return it, or FALSE it is does not exist. The optional second parameter (TRUE) tells the function to also apply the built-in xss_clean() function to the data to remove any potential cross-site scripting (XSS) attempts.

Adding the bid to the database

If we recall in part 3 we created a database to store the details of all the bids. The database had 5 fields:

• id
• entry_id
• member_id
• bid_amount
• bid_date

We have the entry_id and bid_amount from the form, and the id field will be automatically generated as a primary key for the row, which leaves just member_id and bid_date to find.

The form to place a bid was only available to registered and logged-in users, so we can be confident that the bid was placed by a valid member. The Session class stores information about the current member and the userdata function can be used to retrieve the visitor’s member_id:

The Localization class allows you to fetch the current time:

CodeIgniter’s Active Record Database class makes inserting this bid as simple as adding the data to an array and passing it (with the table name) to the insert function:

(Note: we’d normally want to do some validation of the data before adding it to the database - we’ll come back to that in a future article).

What next?

After submitting the form, it’s likely we’d want to display a success message and return the user back to the site.

For the time being, we’ll keep this simple, again using some of EE’s built-in functions:

The Function class’s fetch_site_index() method will return the URL of the site’s homepage. This is where we’ll send users (for now) once the have placed their bid.

The Output class has a show_message() function that will display a ‘standard’ EE message box.

It takes 4 parameters:

• title sets the browser window’s title
• heading sets the message box’s heading
• content provides the message to display
• link is an array containing the URL to return to, and the return link’s text

Summary

There’s still some work to do on the form processing before we can be happy with it (eg, validation), but we now have a form that accepts the visitor’s bid and stores it in the database.

• each auction item is associated with a channel entry which stores all the the information about the item. Our module will store details about any bids for the item.
• only registered and logged in members can place a bid

In our module class (mod.auction.php) we need to add a tag to create the form to handle the bid: {exp:auction:form}. In our mod.auction.php file we need to a form() method (remember, the module’s function name matches the tag’s third segment).

ExpressionEngine forms (for example, the comment form) assume nothing about how the form is laid out. All we need to do is add the form’s opening and closing tags and assume that the developer using the form includes all the necessary form elements (with the correct names)

Making sure we have all the data

Let’s make sure we have all the data we need to save the bid. When we designed the exp_auction database table earlier we decided we’d need:

• which entry the bid is for
• the current user
• the bid amount
• the current time

The bid amount is an element of the form, so will be passed when the form is submitted.

The current user and current time we’ll set when the bid is actually submitted (rather than when the form is created) so we’ll find these later.

The only data we still need to add to the form is the item’s entry_id. There are 2 ways we could do this:

1. we could nest the {exp:auction:form} tag within the {exp:channel:entries} tag and supply it as a parameter to form tag (like we did with the {exp:auction:summary} tag)
2. we could get the {exp:auction:form} tag to work out which entry it should use from the current URL. This will only work if the form is used on a single-entry page, but this is often the case and is a useful technique to use.

For simplicity’s sake we’ll use the first option and pass it as a parameter. We’ll look at the second option later.

As with the summary tag we can now use $entry_id = $this->EE->TMPL->fetch_param(‘entry_id’); to fetch the entry id.

So we have all the data we require for now, so let’s build the form.

Building the form

To add the opening <form> tag we use the function: $this->EE->functions->form_declaration(). Using the provided function has a few advantages that we’ll see later.

This is how our form method in mod.auction.php will now look:

We pass the $form_data array to the form_declaration() function to construct the <form> tag. The $form_data array itself contains an array of hidden form variables (as if we’d used ` tags) which stores the value of the entry_id that we fetched from the parameter.

If we look at the HTML that this generates, we’ll see:

The form_declaration() function has added another 2 hidden fields: XID and site_id

The site_id refers to site if you are using the Multi Site Manager

The XID variable is used to prevent spam and protect against Cross Site Request Forgery (CSRF) - we’ll look at this in more detail later.

The other thing to note is that the form’s action parameter has been set to the site’s index.php page. Obviously, at the moment, this page is not expecting to handle the auction’s form submission. We need to tell the form where to send its data by adding an action.

Actions

An action allows us to set up a URL that will call a specific module’s function. The URL will all have the format: http://site.com/index.php?ACT=id where id will tell EE which action to use.

Actions are stored in the exp_actions table which has a simple structure containing 3 fields: id, class, method.

When EE receives a request with the ACT= query string, it will look up the id in the exp_actions table and (if it exists) call the appropriate class method it finds.

We need to add an action for our module so let’s go back to our upd.auction.php file and modify the install method to add it when the module is installed.

When we’ve added this, remove and install the module again to create the action. This will remove any existing data (if we had any) which would obviously be a bad thing to do in a live environment, but as we are still in development it is not a problem yet. We’ll look at how to safely make updates in a later article.

This should have added a line to the exp_actions table.

This new action points to the Auction class’s method place_bid so we need to this function to the mod.auction.php file:

Finally, to tell the form to send its data to this action we need to update the form() method and we do this by adding another hidden variable:

The $this->EE->functions->fetch_action_id() provides an easy way to fetch the action id given the class and method name (the action id will change if the module is re-installed, whereas the class and method name won’t).

Summary

To recap, we’ve created a template tag to build a form. We then added an action and told the form to post its results to it. On receiving the form the action then tells the system which class and method should handle the response.

In the next article we’ll add the data from the form to the auction database table.

On the listing page, we want to display a list of all the auction items. All the basic information about the item will be stored in a normal channel entry, so we need to add a channel to store the items that we are auctioning.

Create a channel

In Admin > Channel Administration create a channel and a field group. We don’t need this to be fancy - in fact we don’t really need any custom fields - but we’ll add an image and a description (with field names {auction_image} and {auction_description}). We’ll add a few test item to auction too.

We can now display a list of all the items with a basic {exp:channel:entries} tag:

In addition to the basic channel entry data we also want to display the item’s current auction price and the number of bids it has received. This is where our module comes in.

Add a tag to our module

The first tag we need our add to our module is to display the auction status: the current bid and how many bids have been placed.

Module tags are composed the same way as plugin tags and are made up of 3 segments, eg, {exp:short_name:function}. The first segment is always exp which tells the system it has encountered a tag. The second segment is the module’s short name and tells EE which module to use. The third segment is the tag’s function - it explains what the tag will do - and its name exactly corresponds to a method in the module’s class.

We’re going to call our tag {exp:auction:summary} so in our mod.auction.php file we need to add a summary function:

Like plugins, module tags can be single tags or tag pairs. If you use a tag pair, the content between the opening and closing tags is available to the module. Often this content will contain variables that can be replaced by the module.

We’re going to use the summary tag as a tag pair, like this:

And the tag will have 2 variables {current_bid} and {total_bids}.

Using the Template class

We need to fetch the text between the opening and closing tags. EE’s Template class provides a simple variable to do this:

We then need to replace the variables (current_bid and total_bids) in $tagdata with the required values. We could simply use the PHP function str_replace to do this. For example:

(Note that EE adds an LD and RD constants that correspond to the { and } characters of the tag.)

This function will return currently hard-coded values of “0.00” and “0” for the current_bid and total_bids variables.

However, the Template class offers a more powerful way to do this.

A better way

By providing the $this->EE->TMPL->parse_variables() method with the tagdata and an array of variables, it will:

• replace all the variable tags with their values
• handle any date formatting that is required (eg, {date format="%d/%m/%Y"})
• automatically prepare conditionals for any variable you provide (eg, {if total_bids > 5}Hot!{/if})

If you are returning multiple rows of data (we’ll come to that later), it will also provide

• {count}
• {total_results}
• {switch}

variables for you automatically.

There is more information about the parse_variables() function here, and we will be using it to display most of our tags.

Adding this to our function gives us:

The one thing to note here is that the parse_variables function can be used to output multiple rows of data. Our tag only requires a single row so out $data array is stored as an element of the $variables array.

Tag parameters

We’ll look at one more Template class function that we’ll need to use: fetch_param().

Our {exp:auction:summary} tag will need to know which auction item we are looking at. If we were on a ‘single-entry’ page (ie, a page that is only displaying the details of one entry) we could fetch the entry information from the URL., but as we will be using this tag on listing pages (where multiple entries will be shown) we’ll need to tell it which entry we are displaying the information for.

To do this we’ll add an entry_id= parameter to the tag:

We can then use the fetch_param() function to find the item’s entry_id:

If the entry_id= parameter is not provided in the tag, the fetch_param() method will return FALSE. If this happens in our summary() function, we will return an empty string to replace the tag (ie, we will not display anything). On other occasions you might want to display an error or an alternative result. You can also make the fetch_param() function return a default value, by using a second, optional parameter.

Summary

Our module’s summary tag is now replacing its variables and displaying, but we’re currently hard-coding the auction item’s details.

In the next article, we’ll look at adding the form to allow users to place a bid, before returning to our summary function to finish it off by displaying the correct results from the database.

In order to store details of who has bid for what, the module will need its own database table. This table needs to store:

• who has made the bid
• which item the bid was for
• the value of the bid
• what time the bid was placed

Remember, that we will be re-using as much built-in EE functionality as we can, so all the data about the auction item is going to be stored in a channel entry, and only logged-in members can bid.

This means we the data need to store is:

• the member id of the currently logged in user
• the entry id of the relevant channel entry
• the value of the bid
• the current time

Creating the database table

This table needs to be created when the module is installed, so we’ll add it to the install method of our upd.auction.php file.

We’ll modify the install function of upd.auction.php to create the database table:

This sets up an array of fields that we want to add. As well as the 4 fields we identified above, its good practise to include a primary key field to uniquely identify each record.

CodeIgniter provides a Database Forge class to make it easier to manage databases. Note, we don’t need to add the prefix that EE uses at the start of the table (by default, exp_) - although we could - the EE database functions are intelligent enough to do the right thing.

How do we know what type of field we need?

In our case three of our fields - the member id, the entry id and the time - are all common fields in the EE database. The member id and entry id are primary keys in the exp_members and exp_channel_titles tables so it makes sense to use the same definitions as those tables:

The bid amount will be a currency value, so we can use:

for this field.

In EE, dates and times are stored as UTC (Universal Coordinated Time, or GMT, Greenwich Mean Time) timestamps. The timestamp is the number of seconds after midnight January 1st 1970. Again, by inspecting the existing database tables, we can find a suitable definition for this field:

Removing the database table

Just as we create the table when installing the module, we must remove it when we un-install the module.

We do that by modifying the uninstall function of upd.auction.php:

Again, we are using the CI Database Forge class to ‘drop’ the table.

Testing the module

Let’s make sure this works before we proceed by installing and removing the module a couple of times. After you have installed the module, you should check and see the table has been created. If this has worked, remove the module and check the table has been removed too.

Summary

The module now creates a database table to store our auction data when the module is installed, and cleans up after itself if the module is removed.

Firstly, we’ll need to name the module and think of a short name that will be used within the module’s template tags and file and folder structure. A logical name for our creation is ‘Auction’ with the short name ‘auction’.

It is worth reading EllisLab’s Style guidelines regarding naming. It is unlikely that another add-on called Auction will be installed, but if you are using a common term it may be advisable to add a prefix unique to you/your company, eg, xyz_auction.

With our name decided, let’s create the folder and file structure of the add-on package:

At its most simple level, a module package has 4 php files and a language folder (which contains a default english folder).

Let’s see what each file does and add the stub contents:

upd.auction.php

The upd file defines what happens when the module is installed, updated or removed.

There are 3 fairly self-explanatory methods: install, uninstall and update.

install is run when the module is installed from the Control Panel. This adds a record in the exp_modules table to let the system know that the module exists. Along with the module’s name and version, we can configure 2 ‘flags’ for the module:

• has_cp_backend is set to ‘y’ if we want the module to have an interface in the Control Panel’s Module section. If your module does not need any back-end configuration or reporting you can set this to ‘n’.
• has_publish_fields is set to ‘n’ unless the module we are building adds custom fields or tabs to the Publish screen.

Finally, the method returns the value TRUE.

mod.auction.php

The mod file handles the front-end interation and is where the template tag parsing occurs.

At this stage of the module, this class is empty apart from the classes’ constructor which creates an instance of the EE superglobal (we’ll inevitably use this later).

mcp.auction.php

The mcp file handles the Control Panel side of the module.

At this stage of the module, this class does not do anything. We’ve included an empty index method - this is the controller that will be called if the Module’s Control Panel is accessed.

lang.auction.php

EE allows users to localize the system to their own language. Module’s should put all of their static text in the language file so that non-English speaking users can create and add their own translated language file.

A module’s language file must contain 2 elements which are used in the Control Panel’s Modules page to display the title and description. In this case auction_module_name and auction_module_description.

Summary

We now have a (very) basic module that we can install and remove.

Project files can be downloaded from bitbucket (Download)

• a database to store module-specific data
• front end template tags
• a form and corresponding action to handle the processing of the form
• a Control Panel interface for managing/monitoring data

With this in mind - and a quick scan of devot:ee to see that one does not exist - let’s build an auction module.

Initially, we’ll keep the module as simple as possible so that the main concepts don’t get lost (we won’t be building the next ebay quite yet). Additional features can be added at a later stage.

This is what we want the module to do:

• display an entry with its current auction price and other summary data (eg, the number of bids placed, the most recent bid).
• display a form to allow logged in site members to place a bid.
• display a list of previous bids for the item.

One thing to to note: where possible, we’ll use the pre-existing functionality of EE. In this case:

• items will be created as normal channel entries
• the module will use the existing EE membership functionality to control who can place a bid

We’ll also provide some tools for the site administrator to:

• View the bids
• Add/edit/delete bids manually

In the next step, we’ll start creating the module.