Articles


Our first module, part 4: adding a tag to our module

Difficulty: Easy

Now let’s turn to the front-end of the website and remind ourselves what we are trying to do.

Module concept

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.

Some dummy auction entries

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

{exp:channel:entries channel="auction"}

    
<h3>{title}</h3>
    <
img src="{auction_image}" />
    
{auction_description}

{
/exp:channel:entries} 

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:

public function summary() {

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:

{exp:auction:summary}
<p>Current bid: &pound;{current_bid} ({total_bids} bids)</p
{/exp:auction:summary} 

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:

$tagdata $this->EE->TMPL->tagdata

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:

public function summary() {
    
    $tagdata 
$this->EE->TMPL->tagdata;
    
    
$tagdata str_replaceLD."current_bid".RD"0.00"$tagdata );
    
$tagdata str_replaceLD."total_bids".RD"0"$tagdata );

    return 
$tagdata;

(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:

public function summary() {
    
    $tagdata 
$this->EE->TMPL->tagdata;
    
    
// Build array of our variables
    
$data = array(
        
"current_bid" => "0.00",
        
"total_bids" => 0
    
);
    
    
// Construct $variables array for use in parse_variables method
    
$variables = array();
    
$variables[] $data;

    return 
$this->EE->TMPL->parse_variables$tagdata$variables );

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:

{exp:channel:entries channel="auction" ... }
...
    
{exp:auction:summary entry_id="{entry_id}"}
    
<p>Current bid: &pound;{current_bid} ({total_bids} bids)</p
    
{/exp:auction:summary}
...
{/exp:channel:entries} 

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

public function summary() {
    
    
// Find the entry_id of the auction to display
    
$entry_id $this->EE->TMPL->fetch_param('entry_id');
    if( 
$entry_id === FALSE {
        
return "";
    
}
    
    $tagdata 
$this->EE->TMPL->tagdata;
    
    
// Build array of our variables
    
$data = array(
        
"current_bid" => "0.00",
        
"total_bids" => 0
    
);
    
    
// Construct $variables array for use in parse_variables method
    
$variables = array();
    
$variables[] $data;

    return 
$this->EE->TMPL->parse_variables$tagdata$variables );

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.

 

Comments

Hi! Incredibly grateful for you putting this tutorial together. I’d love to use it as my first dive into EE module development, but wanted to know if you were still planning on finishing it. Thanks!

Posted by Matt on May 9, 2012

Hi Matt,

Thanks for your comment.

I’ve just finished the draft for the next part. It’ll hopefully be online in the next week.

Andrew

Posted by Andrew on May 9, 2012

Great, thanks so much!

Posted by Matt on May 9, 2012

The next part - adding a form  - is now online.

Posted by Andrew on May 13, 2012

Excellent. Thanks again. Looking forward to the rest of the tutorial!

Posted by Matt on May 17, 2012

So, I’m new on EE.
I’m do this tutorial and I don’t understand a part.
when talk about “Create a channel”.
I created the channel and a category and now ?
how I do for have my list items as is this tutorial ?

Posted by helton alves on May 2, 2014

Add a comment

(Your email address will not be displayed on the site, but will be used for your gravatar)

Notify me of follow-up comments?