Netjuke Module Development Guide
Initial Revision : 3/27/2003
By : Blake Watters <sbw@ibiblio.org>

Introduction -

    Recently Netjuke has taken on a variety of new users who are in need of special functionality to make
their experience more fulfilling. Additionally, a wide number of new features are not easilly implementable
across the multiple platforms Netjuke caters to. In order to bridge the gap and allow all interested parties
the widest number of options, I have elected to define a simple modular API for Netjuke developers to use in
their hacking of the source. The methodology of this module system is to use a single call to invoke a module
at any point in the Netjuke source and add new features seamlessly. This should make maintaining a patched source
tree much easier and allow us to share our special purpose features in a simple manner. Extra modules will now be
supplied in the Netjuke toolkit.

API Defintion -

    The following functions must be defined by your module for it to function.
    
Initialization Function -

    This function will be called from within the preference file of the Netjuke source (in other words, by the
    common library) and will allow you to do any global setup that needs to be done on any page load.

    Definition : Input : None, Returns : Nothing
        function netjuke_module_init ()

Information Function -

    This function returns an array of information about your module, including what it is supposed to do, where it is
    located and what it is called.

    Defintition : Input : None, Returns : Array ('name', 'file', 'description')
        function netjuke_module_info ()

Installation Function -

    This function performs any installation necessary for your module to function (SQL, etc).
    
    Definition : Input : None, Returns : Boolean indicating success/failure
        function netjuke_module_install ()

Uninstallation Function -

    This function uninstalls and cleans up any data related to your module.
    
    Defintion : Input : None, Returns : Boolean indication success/failure
        function netjuke_module_uninstall ()

Is it installed? Function -

    This function returns a true/false value if the module is installed. If the module requires no installation, it returns
    true.


    Definition : Input : None, Returns : Boolean indicating installation status
        function netjuke_module_installed ()

Registering and Invoking Your Module -

    Once you have defined your module and placed it into the var/modules directory, you are ready to register your
    module in your Netjuke installation. Simply open up your preference file (etc/inc-prefs.php), and add a call to
    register_module ().
    
    Definition : Input : String file, String Unique name , Returns : Error Code
        // File must be relative to netjuke root, name must be unique
        // Calls to this function should be placed in configuration file
        // Errors : -1 File Not Found, -2 Permission denied, -3 module name already exists
        // else returns numeric index for this module
        function register_module ($file, $name)
    
    Once your module is registered, you can pepper call to call_module throughout the Netjuke source tree. These calls
    will invoke the specified function within your module and allow you to add an arbitrary block of code into Netjuke
    at any point.
    
    Definition : Input : String/Integer module name/id, String function name
        // Module may be numeric or textual, function is valid function name in module file
        // additional arguments will be passed to specified function
        function call_module ($module, $function)
