   =========================================================
   ||  Guidelines for writing a Media Mate Module (MMM).  ||
   ||              Author: Tony Collins                   ||
   ||          Updated by: Jamin  Collins                 ||
   ||                   Draft 003                         ||
   ||              Friday, 12 Sep 2003                    ||
   =========================================================


 --------
 Overview
 --------
It is expected that all modules will follow these same basic design principles.
Every part of a module is to be stored inside a single directory, which is then
placed under the modules/ directory.  You are welcome to reference application-
wide scripts within your module, but no module scripts are to be placed outside
your module's directory.  See the Movies Module for examples; it is included
with every Media Mate distribution.

 ------------------
 Naming your Module
 ------------------
The name of the directory containing your modules's files must be less than
twenty characters long, and all lowercase.  Check the availability of other
modules before naming yours.  Your proposed name might already be taken.
Do not name your module 'global'.


 -------------------------------
 Interfacing with the front page
 -------------------------------
The front page operates simply.  It scans the modules/ directory to see if
there are any subdirectories.   It then looks in each subdirectory for a file
named summary.php, and includes it in the front page.  It's that simple.  Your
summary page should generate a simple error if your installation script hasn't
been used yet (see Module Installation, below).  You should also have a file
named 'index.html' that performs a simple redirect to ../../index.php to stop
people browsing your module directory.

Because your pages are included as part of the front page, you can omit many of
the usually required tags in your pages.  Here is a brief list of tags that you
can omit:

<html><head><title><body>

All that's needed on your pages is the actual content.  It is your choice if
you wish to use <div> or <table> tags for layout.

If you would like to include anything in the headers of the front page, create
a file called head.php, and add your headers there.  You do not need to use
<head> and </head> tags in head.php.


 -----------------------------------------
 Linking to other pages within your module
 -----------------------------------------
The front page expects to see links in this form:

index.php?module=yourmodulename&do=pagename

When Media Mate sees links like this, it then looks in the
modules/yourmodulename/ directory for the pagename.php file, which it then
includes as part of index.php.  You are then able to add whatever variables to
your link as you wish.

The only exception to this linking scheme is when retrieving information on
users, when you omit both the $modules and $do variables.  This is because the
files for history and user manipulation are in the root of the mediamate/
directory.


 ---------------------
 Linking to User pages
 ---------------------
When linking to User Details page, use the following scheme:

details.php?id=5

Where '5' is the user's ID number.   Your module should never modify any User
information directly.  Media Mate has built-in methods for doing that.


 ------------------
 Referencing images
 ------------------
When referencing images, you must prefix all directory names with
'modules/yourmodulename/'.  This is because your pages effectively become part
of index.php, which needs the full path to your images.  Consider the following
example:

<img src="modules/yourmodulename/images/foo.png">


 ----------------------
 Database naming scheme
 ----------------------
You are free to use as many database tables for your module as you wish.  For
consistency, always prefix your tables with your module name, as demonstrated
by the Movies module:

movies_list = This is where all the movie details are stored.
movies_prefs = Any preferences specific to the Movies module are stored here.

All database tables that pertain to the whole application are prefixed with
'global', as seen below:

global_users = Where all details on Media Mate users are stored.
global_prefs = Application-wide preferences are stored here.
global_history = Borrowing history is stored here, with userID and module name.

Never name any of your module's database tables 'global', as it is clearly
reserved for application-wide storage.

 -------------------
 Module Installation
 -------------------
Since your module is self contained, the user will just drop your module into
the modules/ directory.  You should include a php script to install your
module's database tables.  Make it very clear that it is the installation
script by naming it 'install_module.php' or something very similar.  Running
the script a second time should do nothing.  We don't want anyone accidentally
overwriting their database tables.

 ------------------
 Global Preferences
 ------------------
Media Mate has a small list of application-wide preferences.  They are all used
by the Movies Module, but you can pick which ones your module needs to
reference.  You can retrive the global preferences into an array using the
following code:

<?php
$global_prefs = $mm->getGlobalPrefs();
?>

You then retrieve the individual preferences from the array with code like
this:

<?php
$global_prefs['preference'];
?>

Where 'preference' is one of the following:

theme = The application wide theme/style name.
online = If set 'on', then the system is connected to the wider internet.
mta = If set 'on', there is a mail transport agent installed on the system.
j_server = The Jabber server used to send messages.
j_port = The port through which we connect to the above Jabber server.
j_username = The Jabber account through which we send messages.
j_password = Password for the Jabber account above.
lang = The application-wide translation.

Your module must not be able to change the application-wide preferences. You
are free to implement preferences specific to your module, but use a seperate
database table for them.  You will also have to write a function to retrieve
them into an array.


 ---------------
 Database Access
 ---------------
The functions for accessing the database have been included in the front page,
which is another reason why all your scripts should conform to this guide. We
have a small class called 'MediaMate' with database functions inside.  Never
write a module to be database specific.  We have abstracted the database
functions into the 'MediaMate' class in order to provide Media Mate with
support for different databases (in a future release).  An example of how to
query a database using the MediaMate class follows:

$result = $mm->dbQuery("SELECT * FROM global_users WHERE user_id = '5'");

Refer to functions.inc.php for the other common database functions.


 ------
 Themes
 ------
Media Mate has a built-in theming system, using CSS.  You should refer to the
Pastel theme for tips on how to make your module match the rest of the
application.  Also see the Movies module for tips.

As described above, your module's 'head.php' is included in the <head> tag of
the front page, so theoretically you are able to define your own extra CSS this
way.  Having said that, you should try to adhere to the application-wide theme
system as much as you can.


 ---------------------
 Borrowing and History
 ---------------------
If your module has the capability to allow users to borrow items, then you
should include history functionality.  The database table 'global_history' can
be used for each borrowing transaction.  Two scripts are required in order to
retrieve history from the database:

history.php is for display of item history.  You can choose your variables.

userhistory.php shows user borrowing history for your items.  The global user
   details page will pass the variable $id to your userhistory.php script.
   This variable should be used when retrieving history items from the
   database, like the following example:

   $sql = "SELECT * FROM global_history WHERE media_type = '$module' 
      AND borrower_uid = '$id'";
   $result = $mm->dbExec($sql);

Here is a brief explanation of what to enter in each field of the
'global_history' table.

entry_id = This is automatically incremented.  Don't ever write anything to
   this field.  
media_id = Enter the unique key of your item in here.
media_type = This is your module name, the same as your module's directoy name.
borrower_uid = The user id of the user who borrowed the item.
date_borrowed = This is a human readable date format, generated by the
   following php code:  $today = date("l, j M Y");
date_returned = Also a human readable date format; for when the item was
   returned.


 -----------
 Translation
 -----------
Your module must have the ability to be translated to other languages, and must
use the following directory structure and filename example:

modules/yourmodulename/lang/en.php

"en.php" contains an array with English text strings stored in different keys.
The front page automatically includes your language if it matches the language
in the Global Preferences.

Other translatable files should be stored in directories prefixed by the
language code, as with these examples from the Movies module:

modules/movies/lang/en.help/adduser
modules/movies/lang/en.lists/genres.php


 ---------------------
 Packaging your module
 ---------------------
Please consider letting us know about your module.  With your permission, we
would like to include it for download on the Media Mate website.  When
packaging your module, please use either the ZIP format, or a gzipped TAR file.
Since all of your files are within one directory, simply package that single
directory.  We want users to be able to uncompress your package into the
modules/ directory, and expect it to work.  Let us know about your module by
emailing MediaMate [at] Rocks [dot] cc.

Please attach your module to a Feature Request on the Media Mate bug/request
tracker.

