Documentation 2.x and 3.x

Docs | Plugins | Administration generator

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 / 5 - 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 / 5 - 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 / 5 - 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 / 5 - 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 5 / 5 - install new plugin

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:

Address book plugin example in ImpressPages CMS

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 5.

ip_plugin_examples_address_book_1.00.zip

Write a comment

You must be logged in to comment.