Articles


Our first module, part 2: setting up the file structure

In future it will probably be easier to use a tool to create the add-on package, but as this is our first module, we’ll do it manually this time.

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:

The Auction module file structure

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.

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

class 
Auction_upd {
    
    
public $version '1.0';

    private 
$module_name "Auction";
    private 
$EE;
    
    
// Constructor
    
public function __construct()
    
{
        $this
->EE =& get_instance();
    
}
    
    
/**
     * Install the module
     *
     * @return boolean TRUE
     */
    
public function install()
    
{
        $mod_data 
= array(
            
'module_name' => $this->module_name,
            
'module_version' => $this->version,
            
'has_cp_backend' => "y",
            
'has_publish_fields' => 'n'
        
);
        
$this->EE->db->insert('modules'$mod_data);
        
        return 
TRUE;
    
}
    
    
/**
     * Uninstall the module
     *
     * @return boolean TRUE
     */
    
public function uninstall()
    
{
        $this
->EE->db->select('module_id');
        
$query $this->EE->db->get_where('modules'
            array( 
'module_name' => $this->module_name )
        );
        
        
$this->EE->db->where('module_id'$query->row('module_id'));
        
$this->EE->db->delete('module_member_groups');
        
        
$this->EE->db->where('module_name'$this->module_name);
        
$this->EE->db->delete('modules');
        
        
$this->EE->db->where('class'$this->module_name);
        
$this->EE->db->delete('actions');
        
        
$this->EE->db->where('class'$this->module_name.'_mcp');
        
$this->EE->db->delete('actions');
        
        return 
TRUE;
    
}
    
    
/**
     * Update the module
     *
     * @return boolean
     */
    
public function update($current '')
    
{
        
if ($current == $this->version{
            
// No updates
            
return FALSE;
        
}
        
        
return TRUE;
    
}
    
}

/* End of file upd.auction.php */
/* Location: /system/expressionengine/third_party/auction/upd.auction.php */ 

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.

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

class 
Auction {
    
    
public $return_data;
    
    
// Constructor
    
public function __construct()
    
{
        $this
->EE =& get_instance();
    
}

}
/* End of file mod.auction.php */
/* Location: /system/expressionengine/third_party/auction/mod.auction.php */ 

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.

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

class 
Auction_mcp {
    
    
public $return_data;
    
    
// Constructor
    
public function __construct()
    
{
        $this
->EE =& get_instance();
    
}

    
/**
     * The module's Control Panel default controller
     *
     * @return void
     */
    
public function index()
    
{
    }

}
/* End of file mcp.auction.php */
/* Location: /system/expressionengine/third_party/auction/mcp.auction.php */ 

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.

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

$lang = array(

    
/* Required for ADD-ONS > MODULES page */

    
'auction_module_name' => 'Auction',
    
'auction_module_description' => 'A simple module to allow entries to be auctioned',

    
/* Required for CONTROL PANEL pages */

    /* Required for FRONT END module */
    
    
    
    
'' => ''
);

/* End of file lang.auction.php */
/* Location: /system/expressionengine/third_party/auction/language/english/lang.auction.php */ 

Summary

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

Project files can be downloaded from bitbucket (Download)

 

Comments

the same code off bitbukket does nto include the code in this course.

Posted by vincej on April 24, 2013

Magnificent website. Lots of useful information here. Im sending it to some friends ans also sharing in delicious. And obviously, thanks for your sweat! eadcekfkadekabkg

Posted by Smithg597 on June 22, 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?