[phpMP-CVS] CVS: phpMP/docs MODULES,NONE,1.1

[Brian R. <hei...@us...>]

Update of /cvsroot/phpmp/phpMP/docs
In directory usw-pr-cvs1:/tmp/cvs-serv4284

Added Files:
	MODULES 
Log Message:
Added MODULES doc.

--- NEW FILE: MODULES ---
This file is used for reference in order to help you create phpMP modules for yourself.
Please do not use this file maliciously.

phpMP Modules come in two flavors.  The first is a standard, paged module.
These are accessed through the modules.php script and follow the following
scripting guidelines.

The second type of module is a 'blocked' module.  These are contained within
the right- and left- side block areas and are used for polls, menus, and
general information that only takes up a small amount of space.


/********************************************************************************
CREATING PAGED MODULES
********************************************************************************/
Let's begin!  To start, here is a basic module broken down into a few simple pieces:

<?

$file = 'sample_module.php';  // File this code is contained in. 

class Module {  // Standard.  ALWAYS included.

  var $pagetitle;  //Area for initialization of Module variables.
  
  function Init() {  // $Module->Init() is auto-called by the module script...use it to initialize stuff.
    $this->pagetitle = "Sample phpMP Module";  // Sets pagetitle var (duh!).
  }
  
  function MakeContent() {  // This creates the actual content displayed on the page.
                            // If you need to call other functions after this one, call them at the end.
    global $Template;       // Makes the $Template class global.
    $Template->Blocking('BeginBig', array(PAGETITLE => ".:: phpMP :: " . $this->pagetitle . "::."));  // Begins a 'big' middle block.
		
		print "This is a test...<br>This is only a test...<br>\n";  // Prints a line.

	  $Template->Blocking('EndBig');  // Ends a 'big' middle block.
	}
}

$Module = new Module(); // ALWAYS the last line of actual code in a module
                        // unless you are calling module functions.  Without
                        // it, the class is not instantiated.

?>

Note that all modules must reside in the modules/ directory within
the phpMP root.

Alrighty...so.  I guess the template object should be explained a bit.
A page is currently assembled in the following order:

  1.  $Template->PrintHeader() - Prints everything up to the left-side menu.
  2.  $Template->CreateSide('left') - Creates the left-side menu and table.
  3.  $Template->Blocking('BeginMain') - Begins the main/mid section of the table.  Used for main content.
      If this is not called, most designs will be thrown COMPLETELY out of whack.
  4.  $Module->MakeContent() - Creates module content.  Should contain BeginBig and EndBig statements.
  5.  $Template->Blocking('EndMain') - Ends the main/mid section of the table.
  6.  $Template->CreateSide('right') - Creates the left-side menu and table.
  7.  $Template->PrintFooter() - Prints copyright and any additional info needed.

Next I'll explain the DBA class.  It is used to access databases.

  $DBA->connect()           - NEVER, EVER CALL THIS FUNCTION!!!!!!
  $DBA->close()             - NEVER, EVER CALL THIS FUNCTION!!!!!!
  $DBA->query()             - Used to execute basic queries from a database.
  $DBA->num_rows($qid)      - Finds the number of rows in specified query ($qid).
  $DBA->fetch_array($qid)   - Fetches an array of values for query ($qid).
  $DBA->fetch_row($qid)     - Fetches a row for query ($qid) in an array.
  $DBA->affected_rows($qid) - Equiv of mysql_affected_rows($qid).

To add a module to the menu and/or modules list, use the following DB row layout:

  name      - Text for link in menu, as of now.
  unixname  - Unix-qualified name of module..only a-z, 0-9, -, and _ chars.
  active    - Set to 1 in order to display in link list or function at all.
  filename  - Filename within modules/ directory.


/********************************************************************************
CREATING BLOCKED MODULES
********************************************************************************/
Now we'll move on to blocked modules.

These are relatively simple.  While not object-oriented, you may create an object
which may then be used to gather the required data.

A blocked module returns two values (or, at least, only two that are used).
These values are:

  $blockname - Title that is displaye in headerbar of block.
  $content   - The HTML used to produce the main content of the block.

The following is an extremely simple example version of a phpMP blocked module:

<?

$blockname = "Whazzup, " . $MPCONF['USR']['username'] . "!";
$content   = "I can't believe you came back!!!!";

?>

As you may have noticed, we introduced a new element into the fray.  The $MPCONF
array is a multi-dimensional array used to store all configuration variables used
within phpMP.  This array will be documented soon.

Anyhow, once included and called for assembly, this would produce a block
resembing this:

+----------------------+
| Whazzup, <username>! |
+----------------------+
| I can't believe you  |
| came back!!!!        |
|                      |
+----------------------+


Pretty simple, huh?

To make the block actually appear, you must add a row to the phpmp_blocking table.
This is the following format for a typical blocked module row:

  blockname - Used if $blockname can be static.  You may then ommit the $content var.
  side      - Right or Left.  Self Explanatory.
  weight    - lowest number comes first i.e. a module with a weight of 1 is displayed
              above one with a weight of 2.
  content   - If block is COMPLETELY static with no PHP, you may put the $content here.
  is_php    - Set to one if using external file.  Set to 0 if content column is set.
  php_file  - Filename of file in modules/ directory i.e. sample_side.php.

NOTE:  As a general rule of thumb, blocked modules should always have _side appended to
       the filename in order to not conflict with a paged module of the same name.