Address Book plugin example

This tutorial will show how to create plugin with managed contact list. We will name it "Address Book" and place it in group "Examples". You will learn how to create functional management tools in minutes.

Step 1 - folder structure

First of all we need to create folders "examples" and "address_book" in "ip_plugins" folder like that:

...
ip_libs
ip_plugins
examples
address_book
ip_themes
...

Step 2 - create manager class

In "address_book" folder create "manager.php" and "items_area.php" files. This file is executed when we open a plugin tab in administration area. We will include standard data management module "std_mod". This class will automatically generate all required management tools to insert, delete, update and search data records in database.

Put this content to "manager.php" file:

<?php        
        
namespace Modules\examples\address_book;        
        
if (!defined('BACKEND')) exit;  //this file can't be acessed directly        
        
require_once(BASE_DIR.PLUGIN_DIR.'examples/address_book/items_area.php'); //include class that describes database structure and how to manage the records in it        
        
class Manager{        
  var $standardModule;         
           
  function __construct() {        
    $itemsArea = new ItemsArea();  //this class is in file items_area.php        
    $this->standardModule = new \Modules\developer\std_mod\StandardModule($itemsArea); //create management tool        
  }        
        
  function manage() {        
    return $this->standardModule->manage();  //return management tools        
  }        
}

Put this content to "items_area.php" file:

<?php                   
                   
namespace Modules\examples\address_book;                   
                   
if (!defined('BACKEND')) exit;  //this file can't be accessed directly                   
                   
require_once(BASE_DIR.MODULE_DIR.'developer/std_mod/std_mod.php'); //include standard module to manage data records                   
                   
class ItemsArea extends \Modules\developer\std_mod\Area{  //extending standard data management module area                   
                   
  function __construct(){                    
    global $parametersMod;  //global object to get parameters                   
                   
    parent::__construct(                   
      array(                   
      'dbTable' => 'm_examples_address_book',  //table of data we need to manage                   
      'title' => 'Contacts', //Table title above the table (choose any)                   
      'dbPrimaryKey' => 'id',  //Primary key of that table                   
      'searchable' => true,  //User will have search button or not                   
      'orderBy' => 'row_number',  //Database field, by which the records should be ordered by default                   
      'sortable' => true,  //Does user have a right to change the order of records                   
      'sortField' => 'row_number'  //Database field which is used to sort records                   
      )                       
    );                   
                      
    $element = new \Modules\developer\std_mod\ElementText(  //text field                   
    array(                        
    'title' => 'Name',  //Field name                   
    'showOnList' => true,  //Show field value in list of all records                   
    'dbField' => 'name',  //Database field name                   
    'searchable' => true  //Allow to search by this field                   
    )                   
    );                   
    $this->addElement($element);                       
                   
                       
    $element = new \Modules\developer\std_mod\ElementText(                   
    array(                   
    'title' => 'Email',  //Field name                   
    'showOnList' => true,  //Show field value in list of all records                   
    'dbField' => 'email', //Database field name                   
    'regExpression' => $parametersMod->getValue('developer','std_mod','parameters','email_reg_expression'),  //Check if inserted value is correct email address                   
    'regExpressionError' => $parametersMod->getValue('developer','std_mod','admin_translations','error_email'),  //Error message if email address is incorrect                   
    )                   
    );                   
    $this->addElement($element);                           
                       
                       
  }                   
                   
}

Step 3 - prepare for installation

In "address_book" folder create "install" subfolder and place "plugin.ini" file with content:

version:1.00

module_title:Address Book

module_key:address_book

module_group_title:Examples

module_group_key:examples

module_managed:1

"plugin.ini" file will tell the system how to install this plugin. But we need a database table to store records. This can be made by installation script. Place file "script.php" in "install" directory with following content:

<?php                     
                     
namespace Modules\examples\address_book;                     
                     
if (!defined('CMS')) exit; //this file can't bee accessed directly                     
                     
class Install{                     
                     
  public function execute(){                     
                     
    $sql="                     
    CREATE TABLE IF NOT EXISTS `".DB_PREF."m_examples_address_book` (                     
      `id` int(11) NOT NULL AUTO_INCREMENT,                     
      `row_number` int(11) NOT NULL,                     
      `name` varchar(255) DEFAULT NULL,                     
      `email` varchar(255) DEFAULT NULL,                     
      `photo` varchar(255) DEFAULT NULL,                     
      PRIMARY KEY (`id`)                     
    ) ENGINE=MyISAM  DEFAULT CHARSET=utf8 AUTO_INCREMENT=121 ;                     
    ";                     
                         
    $rs = mysql_query($sql);                     
                         
    if(!$rs){                      
      trigger_error($sql." ".mysql_error());                     
    }                     
                         
  }                     
}

Step 4 - prepare for uninstall

For clean uninstall we need to drop created table from database. In "address_book" folder create "uninstall" subfolder and place "script.php" file with content:

<?php               
               
namespace Modules\examples\address_book;               
               
if (!defined('CMS')) exit; //this file can't bee accessed directly               
               
class Uninstall{               
               
  public function execute(){               
               
    $sql = "DROP TABLE `".DB_PREF."m_examples_address_book` ";               
                   
    $rs = mysql_query($sql);               
                   
    if(!$rs){                
      trigger_error($sql." ".mysql_error());               
    }               
                   
  }               
}

Step 4 - installation

Login to administration area, go to tab "Developer->Modules" and press "install". Then refresh browser (press F5) and you will see new tab "Examples". Press it and then press "Address Book". You should see:

Now you can insert, update, delete and search your address book records.

Download

You can download this example as an archive. Upload folder "examples" to folder "ip_plugins" on your server and execute actions described in step 4.

ip_plugin_examples_address_book_1.00.zip