File: MODULE_README
Date:	2001/11/17 07:59:27
Author: Adam Morton, adam@tux.appstate.edu
	Ryan Cowan,  ryan@tux.appstate.edu
	modified by Tat Rithaporn, digitaldynomite@yahoo.com
	modified by Jeremy Agee, jagee@tux.appstate.edu
	modified by Alessandro Pisani, alextxm@users.sourceforge.net

Description: This text file describes the basic setup for a module made
             for phpWebSite and is designed to set some standards for
             the development or modules for phpWebSite.

ATTENTION: This document assumes a class-based module though modules
that are not class-based will also work here.

In the new module "style" we are standardizing the naming of files,
variables, and database tables in all modules. To make sure you're
standardized please follow these steps:

1.	Choose a name for your module (we'll say "mymodule").
2. 	Make sure the directory which contains your module code is
   	also named "mymodule".
3. 	Any of the files described below should also have your module's
   	name (ie: "mymodule_config.php, etc").
4. 	If you decide to make your module class-based, the class name should
   	also be "mymodule".
5a.	Make sure all tables created in the database for use with your
	are name "mod_mymodule_tablename".
5b.	Calls to the database should contain the $table_prefix and include the
	config.php file for reference of the table prefix.
	example in mymodule_config.php:
		include('config.php');		// reference table prefix (make sure you have the correct location for config.php)
		mysql_query("SELECT users FROM " . $table_prefix."mod_mymodule_tablename WHERE ....");

6. 	Last but not least, make sure you have an index.php which a switch
   	statement similar to the one shown below.  This is a crucial step
   	since all operations on your module will happen through this file.

There is also a small framework to help start you off. It is under the
directory name "docs/mod_example".

There are several files which you will need to know about in order to
start coding your module or to start converting it to the new "style":

----------------------------------------------------------------------

- mod.php: This file recides in the web root and is provided by the
Web Technology Group. If you learn to use this file you can code your
module any way you wish and ignore the rest of this document. I strongly
recommend, however, that you continue reading and standardize your
module so it can take advantage of upcoming changes in phpWebSite's
structure. Here is the only code contained in mod.php:

include("./mod/$mod/index.php");

The file requires 2 variables to use it correctly. The first variable
"$mod" is simply the name or your module directory (see step 2 above).
The second variable is "$op" and is the operation which is to be
performed by index.php. Once you figure out how to use those, the rest
is a snap.

----------------------------------------------------------------------

- index.php: This file is where all the decisions are made as to what
function to call, whether or not it's an admin function, etc. Basic
setup:

if($admintest == $security_hash)
switch($op)
{
	case "this_admin_op":
	this_admin_op();
	break;

	//DO NOT INCLUDE A DEFAULT CASE!! If you do
	//it will not continue on to the user switch.
}

switch($op)
{
	case "this_user_op":
	this_user_op();
	break;

	case default:
	if(!$op)
	default_operation;
	break;
}

----------------------------------------------------------------------

- module.php: This is the main include file which contains your class
code for your module as well as the class-based functions associated
with your module. Basic setup:

class module
{
	var my_var;

	function module()
	{
		$this->my_var = 1;
	}

	function set_my_var()
	{
		$this->my_var = 2;
	}
}

----------------------------------------------------------------------

- module_config.php: This file contains the configuration variables
specific to your module. Basic setup:

$default_dir = "/usr/local/share";
$num_pages = 3;

etc ...

----------------------------------------------------------------------

- modname_block.php: This file can be used buy your module to display
its contents somewhere on the site.  The location is determined but
block_pos in the modules table. The variable $position can be used
in your block file to determine what location called your block file.
This will only be needed if you plane to have your block in more than
one locate. You will need to send all your output to the variable
$box_content. Also the name of the block file needs to be in the
block_file under the table modules.

----------------------------------------------------------------------

- block_pos: The block_pos column in the modules table determines where
your block is displayed.  Here is a chart of the numbering system.

 0  - Off
 1  - Left
 2  - Topcenter
 3  - Right
 4  - Middlecenter
 5  - Bottomcenter
 6  - Left & Topcenter
 7  - Left & Middlecenter
 8  - Left & Bottomcenter
 9  - Left & Right
 10 - Topcenter & Middlecenter
 11 - Topcenter & Bottomcenter
 12 - Topcenter & Right
 13 - Middlecenter & Bottomcenter
 14 - Middlecenter & Right
 15 - Bottomcenter & Right
 16 - Left & Topcenter & Right
 17 - Left & Middlecenter & Right
 18 - Left & Bottomcenter & Right
 19 - Topcenter & Middlecenter & Right
 20 - Topcenter & Bottomcenter & Right
 21 - Middlecenter & Bottomcenter & Right
 22 - Topcenter & Middlecenter & Left
 23 - Topcenter & Bottomcenter & Left
 24 - Middlecenter & Bottomcenter & Left
 25 - Topcenter & Middlecenter & Bottomcenter
 26 - Left & Topcenter & Middlecenter & Right
 27 - Left & Topcenter & Bottomcenter & Right
 28 - Left & Middlecenter & Bottomcenter & Right 
 29 - Topcenter & Middlecenter & Bottomcenter & Right
 30 - Topcenter & Middlecenter & Bottomcenter & Left
 31 - All


----------------------------------------------------------------------
Install & Uninstall
- module_install.php:
- module_uninstall.php:  This is where you put all the code necessary
for setting up your module initially. (ie: "creating database tables,
pre-populating data into the database, etc"). Again verify that it follows
step 5 criteria above for table name creation.  To setup these files you need
to have two options in your index.php.  The examples below will make you module
compatable with the module installer under the admin menu.  These examples will also
help you return errors during install and make you module install and uninstall secure
buy not allowing some one to just put in ./mod/modname/modname_install.php and have it
install. This will also eliminate the hasle of doing any database connects.

Ex. (index.php)
----cut----
if ($admintest == $security_hash)
{
	switch($op)
	{
		case "install" :
		include("./mod/modname/modname_install.php");
		if(!$box_content)
			$box_content = "No Errors<br />All Done!";
		break;

		case "uninstall" :
		include("./mod/modname/modname_uninstall.php");
		if(!$box_content)
			$box_content = "No Errors<br />All Done!";

		break;		
	}
}
----paste----

Ex.  (modname_install.php)
----cut----
  /* security check */
  global $PHP_SELF;
  if(substr_count($PHP_SELF,"/mod/")) $inc_prefix="../../";
  else if(substr_count($PHP_SELF,"mod.php") || substr_count($PHP_SELF,"admin.php")) $inc_prefix="./";
  else $inc_prefix="../";
  
  include_once($inc_prefix."modsecurity.php");
  include($inc_prefix."config.php");
  
  if(!check_internal_call())
        html_header_location("$phpws_url");
  /* end security check */

 $result = mysql_query("CREATE TABLE " . $table_prefix."mod_modname_example (
  id int(11) NOT NULL default '0',
  name varchar(20) default NULL");

 if(!$result)
	$box_content .= "<br />" . mysql_error();
----paste---

Ex. (modname_uninstall.php)
----cut----
  /* security check */
  global $PHP_SELF;
  if(substr_count($PHP_SELF,"/mod/")) $inc_prefix="../../";
  else if(substr_count($PHP_SELF,"mod.php") || substr_count($PHP_SELF,"admin.php")) $inc_prefix="./";
  else $inc_prefix="../";
  
  include_once($inc_prefix."modsecurity.php");
  include($inc_prefix."config.php");
  
  if(!check_internal_call())
        html_header_location("$phpws_url");
  /* end security check */

  $result = mysql_query("DROP TABLE " . $table_prefix."mod_modname_example");

  if(!$result)
	$box_content = mysql_error();
----paste----

For more detailed info on the new modules structure and its relationship with the Module Installer feature provided in phpWebSite 0.8.2, please refer also to:
 docs/developers/module_installer_api.html

---------------------------------------------------------------------
- $table_prefix
This allows you module to have a table prefix from the phpwebsite
config.php. You can use this in all your SQL statments

" . $table_prefix."

See example above for full SQL statment.  You will also need to
include the phpwebsite config.php file for the $table_prefix var.

---------------------------------------------------------------------

- icon.gif: <OPTIONAL> This file is the icon shown in the admin menu
for your module. Suggested size is roughly 32x32 pixels. You may go
larger if you wish but keep in mind that if someone has several modules
installed it would benefit everyone if the icons were small.

----------------------------------------------------------------------

- Theme Compatibility:  Make sure the modules are theme compatible.
In order for the themes to be compatable, most of the output to the screen
has to be run through the theme functions. These functions are located in
theme.php in the theme directory.  You must also include header.php
and footer.php at the beginning and end of the page.

Basic setup:

include ("header.php");

$box_title = "<center>Delete</center>";

$box_content = "
<center>
<h3>WARNING</h3>
<p>Are you sure?</p>
<p><a href=\"yes.php\">YES</a>|<a href=\"no.php\">NO</a></p>
</center>
";

themesidebox($box_title, $box_content);

include ("footer.php");

----------------------------------------------------------------------

- Database Connectivity :  For new modules to connect to the database
you need to add the following line at the top of your index.php file:

include("dbconnect.php");

----------------------------------------------------------------------
If you would like to research module writing further, check-out the
userpage module in the mod directory of your phpWebSite root. The code
is standarized and class-based. Email any questions or comments to the
phpWebSite Developers List at:

phpwebsite-developers@lists.sourceforge.net

<END OF FILE>
