This document describes EWE modules which is how EWE operations are customized and extended.
Module code must use the method described in section 3.2 to locate the EWE include files.
Providing a module for EWE is fairly simple. Each module must exist in its own subfolder
under the /modules directory, whose name is the module name and (obviously) must be
unique among modules. Within that directory are all of the files necessary to support
the module. The only required one is "x.php", which contains a class named "x" (where
"x" is the module name and the name of the module subfolder) which has the following
methods defined:
Install() - installs the module into EWE. Creates all necessary tables and table entries.
If it returns non-null, it is the name of the file to execute to do the final installation
tasks (such as querying the user). One of the first things to do is to call the
Modules::Add_Module() method to register the module. If this fails, no further installation
tasks should be attempted.
Uninstall() - uninstalls the module from EWE. All tables created during the install
should be removed. EWE removes all hook references to the module, so that is not
necessary for the Uninstall() method's code.
Configure() - User configuration.
Description() - Returns a short description of the module.
Hook() - Respond to hooks (see documentation on hooks).
New_Update() - Returns True if a newer version of the module is available.
Update() - Performs an update to the latest version of the module.
Version() - Returns an integer value indicating the version of the module.
Note that the module name must not contain spaces, dollar signs, or any characters that are not valid for the file system on which EWE is installed.
Do not directly access EWE tables - use the appropriate class methods to maintain data consistency. For instance, use the User class to access user information. This will prevent your module from breaking when EWE is upgraded to new versions. If you are adding new tables, define a new database set name to use (see section 3.1.7). Also, to avoid collision with future EWE table names and the table names of other modules, prefix your table names with your module name.
The following code is an example of a module called "SampleModule". The SampleModule.php file will be placed in the modules/SampleModule folder and the contents of that file are:
<?php
class SampleModule
{
require_once( __DIR__ . "/../../base/prepare.php" );
require_once( __DIR__ . "/../../classes/Modules.php" );
require_once( __DIR__ . "/_SampleModule.php" );
private static function create_table($name,$sql)
{
$s="SELECT * FROM $name";
if($res=db_query($s))
{
if(db_num_rows($res)>0)
{
return 0; // Probably already installed
}
}
if(!$res=db_query($sql))
{
return SQL_error(); // Probably already installed
}
return 0;
}
public function Install()
{
global $db_prefix;
$M = new Modules();
// Add ourselves as a module...
$ID=$M->Add_Module('SampleModule',1);
if(is_error($ID))
{
return $ID;
}
$res=self::create_table($db_prefix.'SampleModule_table1',"CREATE TABLE `".$db_prefix."SampleModule_table1` ".
"( `rowID` INT NOT NULL AUTO_INCREMENT, `timestamp` DATETIME NULL DEFAULT CURRENT_TIMESTAMP, ".
"`page` VARCHAR(45) NULL, `uid` INT NULL, `uuid` INT NULL, PRIMARY KEY (`rowID`))");
if(is_error($res))
{
return $res;
}
$res=self::create_table($db_prefix.'SampleModule_table2',"CREATE TABLE `".$db_prefix."SampleModule_table2` ".
"( `rowID` INT NOT NULL AUTO_INCREMENT, `uuid` INT NULL, `ip` VARCHAR(45) NULL, ".
"`data` INT NULL DEFAULT 0 ,".
"`version` VARCHAR(16) NULL DEFAULT NULL, ".
"PRIMARY KEY (`rowID`))");
if(is_error($res))
{
return $res;
}
// Add privileges...
$E = new EWE();
$E->Add_Privilege(Priv_Report,1,'SampleModule_Report',$ID,'Read data');
$E->Add_Privilege(Priv_Modify,1,'SampleModule_Modify',$ID,'Modify data');
// Add hooks...
$res=$E->Add_Hook(EWEHOOK_HTML_PAGE_END,$ID,-1,$ID,0);
if(is_error($res))
{
return $res;
}
// Add module text...
$T = new Texts();
$T->Add_Module_Text($ID,SampleModule_Text_No_Data,1,'No data available');
$T->Add_Module_Text($ID,SampleModule_Text_Data_Count,1,'Number of items:');
$T->Add_Module_Text($ID,SampleModule_Text_User_Column_Heading,1,'Users');
return 0;
} // Install()
public function Description()
{
return "Sample Module for EWE";
}
public function Version()
{
return 10; // 1.0
}
public function Uninstall()
{
global $db_prefix;
$E = new EWE();
$sql="DROP TABLE IF EXISTS ".$db_prefix."SampleModule_table1";
db_query($sql);
$sql="DROP TABLE IF EXISTS ".$db_prefix."SampleModule_table2";
db_query($sql);
}
public function Hook($hook,$module,$site,$value)
{
global $db_prefix;
global $uuid;
if($hook==EWEHOOK_HTML_PAGE_END)
{
if($uuid!=0) // Ignore bots
{
// do something
}
}
} // Hook
public function Configure()
{
header("Location: ../modules/SampleModule/SampleModule_config.php");
exit;
}
public function New_Update()
{
return FALSE;
}
public function Update()
{
// Intentionally left blank
}
}
The file contains a single class called "SampleModule".
Since the various php files that support our module will share some common code and constants, we include a file "_SampleModule.php" which contains that common information. In this example, we have text constants that begin with "SampleModule_Text_" and privilege constants that begin with "Priv_".
The Create_Table private method is used to construct tables for our module. First we try to select data from the table to see if it is already there. If we suceed, it must already be there and we exit with success code of 0. If not, we attempt to construct the table from the passed SQL. If that fails, we return the error. Otherwise, it succeded and we can exit with 0.
During the Install() method we first register our module by name and exit if there is an error. Depending on the module, we define up to four different things: tables, privileges, hooks, and text. Not all modules will have all (or any) of these. In our example we will use all four. First we create whatever tables are needed by our module, calling the aforementioned Create_Table method. Then we define privileges, the hooks, and finally module text.
The Uninstall() method simply removes any tables created by the Install() method. The Hook() method handles any hook calls that may happen.
The Configure() method is called to allow an authorized user to configure the module. Here we redirect the caller to SampleModule_config.php in order to reduce the total amount of code in this class. The point of the redirect file is to provide a full user interface for configuring the module. If there is no configuration, this method should be left empty. It is important to minimize the size of this file since every requested Hook will open this file to call the Hook() method. The larger this file, the more pronounced will be the effect on the performance of the web site.