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:
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_backendis 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_fieldsis 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)
the same code off bitbukket does nto include the code in this course.
Posted by vincej on April 24, 2013