This document is in alpha state, and as such the description of the API is likely to change. Do not use the functions outlined in this document for development work.
12nd May 2002
Note: Through at least MDPro 1.07, MDP uses the PostNuke API and some references to PN have thus been left intact.
Table of Contents
Table of Contents
The PostNuke API is a set of functions for the MDPro content system that allows developers to access key information and manage their specific content in an easy fashion.
There are a number of advantages to having an API for the MDPro system. Primarily, using an API allows developers to write MDPro-compliant code that they can guarantee will still work whenever MDPro is upgraded. This is especially important for a system such as MDPro as the core functionality of the system is at current very much in flux and is altering rapidly to meet the demands being placed upon it. Having a stable interface into the system is one way of ensuring that the core developers can continue their work on updating and optimizing the MDPro system without continually breaking the code that module developers have written.
Other reasons for using an API include the ability for developers to start working with MDPro more quickly without needing to understand the internals of the system, to have standardized ways of obtaining and manipulating information, and
The main disadvantage of having an API is when you want to do something that it does not have a suitable function for. This problem is addressed by encouraging developers to submit their own suggestions for new API functions, and even the functions themselves, for introduction into the core (details on the procedures for doing this are below).
An API also adds overhead to the entire system, but the trade-off in stability and ease of development more than compensates for this.
The PostNuke API is primarily aimed at developers who wish to write modules for the MDPro system. In addition, some theme designers might use these functions to provide advanced features within their theme.
The PostNuke API is currently in alpha. This means that the API may well have extra functions and arguments added to it. However, all of the functions as outlined in this document will work as described, and continue to work as described for the foreseeable future. Any future versions of the API will note where functions have been superceded or deprecated, and developers will have at least 6 months between any major changes in the API being implemented and the older functions being removed from the core, allowing suitable time for migration.
This document gives an overview of the PostNuke API, and also includes a reference for each official function currently available to developers.
Other documents that might be of use in conjunction with this guide are the Module Development Guide, the Theme Development guide, the Categorized Data Guide, and the Output Functions Guide (all yet to be written).
The PostNuke API is a work-in-progress. There will be many functions that are missing from the API that developers would like. To this end, if a developer has a request for a particular function then they can submit it to the MDPro features request list on SourceForge at the PostNuke Homepage. The same system can be used for sending in updates of current functions or new functions. If you are a developer and currently either globals directly or accessing one of the core tables to obtain or update information then please consider sending in a feature request so that the MDPro team can develop an API to carry out the work instead. This will ensure that your code is more likely to continue working through future versions of MDPro without modification, and that
Please note that the main requirements for the core PostNuke API are stability and a relatively small footprint. Due to this it is possible that your request for a new or updated function will get refused on the grounds that it is too specific or can easily be built from other core API functions. In such situations the MDPro team will always try to provide a simple alternative, but please remember that submission of a new or updated part of the API does not guarantee inclusion.
Table of Contents
The PostNuke API is broken down in to a number of different areas. These areas are as follows:
This area covers everything related to users. Confirming that a user is logged in, getting a user-specific configuration parameter, or logging a user into the MDPro system are examples of functions that fall into this area.
This area covers everything related to modules. Seeing if a particular module is available, setting a module-specific configuration parameter, or loading in a particular module API are examples of functions that fall into this area.
This area covers everything related to security. Checking a user's ability to carry out a particular action and generating unique request identifier keys to avoid spoof and repeat attacks are examples of functions that fall into this area.
This area covers everything related to HTTP sessions. Setting session variables, creating session cookies to pass to the user's web browser, and initializing the PHP settings to allow correct implementation of the allowable security measures are examples of functions that fall into this area.
This area covers everything related to handling of variables. Cleaning and sanitizing user input, correctly escaping information to be stored in a database, and ensuring that filenames do not have operating-system-unfriendly characters in them are examples of functions that fall into this area.
This area covers everything related to output. Creating a table of information, adding a drop-down list to a form, and printing a page for the user are examples of functions that fall into this area.
This area covers everything related to database. Initializing a database connection, getting a handle to a database, and obtaining a list of tables that the database contains are examples of functions that fall into this area.
This area covers any number of other functions that are useful but do not belong to any particular group. Loading the current user theme, getting status messages from the previously run command, and carrying out HTTP redirects to other pages are examples of functions that fall into this area.
Table of Contents
Throughout the API reference, use is made of a type void, especially for specific return values. PHP does not in itself have a type of void, it is used in this document to refer to an unset value. It's very important for you to understand this difference since the the void parameter is heavily used by the exception handling system on which PostNuke API functions are based.
For example, pnModAPIFunc() takes parameters of a module name, type, and function, works out which actual module function to call; it then calls the module function and passes back the return value as its own return value. The problem with this is that if pnModAPIFunc() returned false for a failure to find the specified function then to the developer this would be indistinguishable from the function being found and itself returning false. void return values can be checked with the PHP isset() function, as shown below:
$articles = pnModAPIFunc('News', 'user', 'getarticles');
if (!isset($articles) && pnExceptionMajor() != PN_NO_EXCEPTION) {
// pnModAPIFunc() failed
return; // throw back exception
}
if ($articles == false)
// getarticles failed
} else {
// getarticles succeeded, data in $articles
}
|
Throughout the PostNuke API reference the return values of void and false are distinct. false is returned when an API call functioned correctly but returns a negative response. void is returned when an API call has internal problems and raises an exception. Note that this is a general rule, and there are a few exceptions out of necessity. These exceptions are noted in the reference documentation for the relevant function.
Table of Contents
The following pages have a complete PostNuke API reference. Any functions that are not listed in this section are to be considered internal and should not be used by developers.
pnBlockGetInfo — get block information
array
pnBlockGetInfo(bid);
int bid
;
BAD_PARAM
DATABASE_ERROR
ID_NOT_EXIST
pnBlockGetInfo() returns an array of Block information.
The id of this block in the MDPro system.
This function returns an array of block information or void if an exception was raised.
This function raises BAD_PARAM if you pass an invalid parameter. This function raises DATABASE_ERROR if an error occurs while querying data. This function raises ID_NOT_EXIST if the block is unknown.
The block information array contains the following items:
The display title of the block
The container for block content. Serialized using pnBlockVarsFromContent() and pnBlockVarsToContent().
The url for blocks that depend on URLs, like a rss headlines block.
The position of the block, currently one of 'l' (left), 'r' (right), 'm' (middle). This is likely to change in later versions to make placement more flexible.
The weight of the block, used for vertical placement of blocks.
The status of a block, '1' for active, '0' for inactive.
Indicates if a block should be refreshed. Examples would be headline blocks that fetch external content regularly.
The date and time of the last refresh of the block.
The language of the block.
The ID of the module a block belongs to. '0' indicates a block belonging to the core.
// Get information on block
$blockinfo = pnBlockGetInfo($bid);
|
pnBlockLoad — load a block
bool
pnBlockLoad(modname,
block);
string modname,
string block
;
BAD_PARAM
DATABASE_ERROR
ID_NOT_EXIST
MODULE_FILE_NOT_EXIST
pnBlockLoad() loads a block into the MDPro system.
The well-known name of a module to load the block from. This parameter can be left empty, or set to 'Core' to load core blocks.
The name of the block to load
This function returns true if the module loaded successfully, and void if an exception was raised.
This function raises BAD_PARAM if you pass an invalid parameter. This function raises DATABASE_ERROR if an error occurs while querying data. This function raises ID_NOT_EXIST if the block is unknown. This function raises MODULE_FILE_NOT_EXIST if the block file doesn't exist.
The PostNuke API keeps track of what blocks have been loaded, so multiple calls to pnBlockLoad() with the same parameters will return true each time.
For more information on well-known names of modules please refer to the documentation for pnModGetVar()
This function does not display the block automatically, this must be carried out by a separate call to pnBlockShow().
// Load the past article block from the News module
if (!pnBlockLoad('News', 'past')) {
die('Could not load past articles block');
}
|
pnBlockShow()
pnBlockShow — set configuration variable
string
pnBlockShow(modname,
block,
blockinfo);
string modname,
, string block,
, array blockinfo
;
BAD_PARAM
DATABASE_ERROR
ID_NOT_EXIST
MODULE_FILE_NOT_EXIST
pnBlockShow() gets the output of a block by calling its 'block_display' function.
The well-known name of a module to display the block from. This parameter can be left empty, or set to 'Core' to display core blocks.
The name of the block to load
An associative array of parameters to pass to the block display function. The exact number and type of parameter is block-dependent.
This function returns the output of the block display function is if it succeeds, or void if an exception was raised.
This function raises BAD_PARAM if you pass an invalid parameter. This function raises DATABASE_ERROR if an error occurs while querying data. This function raises ID_NOT_EXIST if the block is unknown. This function raises MODULE_FILE_NOT_EXIST if the block file doesn't exist.
TODO: nail down the block standards. Note that the MDPro block standards state that blocks called in this way have to return output themselves. Especially, they need to implement the '{$modname}_{$block}block_display' function.
TODO
|
pnBlockLoad()
pnConfigGetVar — get configuration variable
mixed
pnConfigGetVar(name);
string name
;
BAD_PARAM
DATABASE_ERROR
pnConfigGetVar() obtains a configuration variable from the MDPro system.
The name of the configuration variable to obtain
This function returns the requested variable if the variable exists. If the variable does not exist then this function will return void. This function also returns void if an exception was raised.
This function raises BAD_PARAM if you pass an invalid parameter. This function raises DATABASE_ERROR if an error occurs while querying data.
The configuration variables available with this release of the API are as follows:
Level of debugging required. 0 is no debugging, 1 is normal debugging.
Version of this MDPro system
ID of this MDPro system; currently always 'MDPro'
Sub-ID of this MDPro system
Name of initial module for this MDPro system to load
Email address of site administrator
Name of this MDPro system
Description of this MDPro system
Timezone offset of this MDPro system, in hours from GMT-12
Security level of this site; one of 'high', 'medium', or 'low'
Flag to state whether advertising banners are shown; '0' for no or '1' for yes
Code of default language for this MDPro system
Locale for this MDPro system
Flag to state whether banned is active; '0' for no or '1' for yes
Array of words that are banned by this MDPro system
Other variables will be made available in future releases of the API.
// Get locale for this site
$locale = pnConfigGetVar('locale');
|
pnConfigSetVar()
pnConfigSetVar — set configuration variable
bool
pnConfigSetVar(name,
value);
string name,
, string value
;
BAD_PARAM
DATABASE_ERROR
pnConfigSetVar() sets a configuration variable on the MDPro system.
The name of the configuration variable to set
The value to set the configuration variable to
This function currently returns false due to not being implemented.
This function raises BAD_PARAM if you pass an invalid parameter. This function raises DATABASE_ERROR if an error occurs while querying data.
This function is not currently implemented.
// Set locale for this site
if (!pnConfigSetVar('locale', 'en_GB')) {
die('Error setting configuration variable');
}
|
pnConfigGetVar()
pnConfigDelVar — delete a configuration variable
bool
pnConfigDelVar(name);
string name
;
BAD_PARAM
DATABASE_ERROR
pnConfigDelVar() deletes a configuration variable from the MDPro system.
The name of the configuration variable to delete
This function currently returns false due to not being implemented.
This function raises BAD_PARAM if you pass an invalid parameter. This function raises DATABASE_ERROR if an error occurs while querying data.
This function is not currently implemented.
// Remove locale setting
if (!pnConfigDelVar('locale')) {
die('Error deleting configuration variable');
}
|
pnConfigGetVar(), pnConfigSetVar()
pnDBGetConn — get database connection
array
pnDBGetConn();
pnDBGetConn() obtains database connection handles for direct querying of the MDPro database.
This function returns an array of database connection values. At current the only active value is the first one, which should be used for all database interaction.
Future versions of the PostNuke API might supply extra connection information through this function, to allow for features such as replicated or failover databases.
// Get database connection
list($dbconn) = pnDBGetConn();
|
pnDBGetTables()
pnDBGetTables — get database tables
array
pnDBGetTables();
pnDBGetTables() obtains database table information for direct querying of the MDPro database.
This function returns an array of database table information.
At current this information is only sparsely documented; more documentation on this array and direct database access for developers is expected soon.
// Get database tables
$pntable = pnDBGetTables();
|
pnDBGetConn()
pnDBInit — initialise MDPro database connection
bool
pnDBInit();
pnDBInit() initialises connections to the MDPro database.
This function returns true if the connections were successfully made, or false if the connections were not successfully made.
pnDBInit() is normally called from within pnInit(), and as such should not be called by developers.
pnInit()
pnExceptionFree — reset exception status
void
pnExceptionFree();
pnExceptionFree() makes a reset of current exception status.
This function does not return a value.
You must always call pnExceptionFree() when you handle a caught exception or equivalently you don't throw the exception back to the callers chain.
pnExceptionId() pnExceptionMajor() pnExceptionSet() pnExceptionValue()
pnExceptionId — return current exception identifier
string
pnExceptionId();
pnExceptionId() returns the string identifying the exception. The character string contains the ID for the exception (its PHP class name).
This function returns the current exception identifier. If invoked when no exception was raised a void value is returned.
pnExceptionFree() pnExceptionMajor() pnExceptionSet() pnExceptionValue()
pnExceptionMajor — return current exception major number
int
pnExceptionMajor();
pnExceptionMajor() allows the caller to establish whether an exception was raised, and to get the type of raised exception. The major PN_NO_EXCEPTION identifies the state in which no exception was raised.
This function returns one of these values: PN_NO_EXCEPTION, PN_USER_EXCEPTION or PN_SYSTEM_EXCEPTION.
pnExceptionFree() pnExceptionId() pnExceptionSet() pnExceptionValue()
pnExceptionSet — raise an exception
void
pnExceptionSet();
pnExceptionSet() allows a function to raise an exception. The caller must supply a value for the major parameter. The major parameter can have one of the values PN_NO_EXCEPTION, PN_USER_EXCEPTION, or PN_SYSTEM_EXCEPTION. The value of the major parameter constrains the other parameters in the call as follows:
* If the major parameter has the value PN_NO_EXCEPTION, this is a normal outcome to the operation. In this case, both exception_id and param must be NULL. Note that it is not necessary to invoke pnExceptionSet() to indicate a normal outcome; it is the default behavior if the method simply returns.
* For any other value of major it specifies either a user-defined or system exception. The exception_id parameter is the identifier representing the exception type. If the exception is declared to have members, the param parameter must be the exception struct (PHP class) containing the members. If the exception has no members, param must be NULL.
This function does not return a value.
pnExceptionFree() pnExceptionId() pnExceptionMajor() pnExceptionValue()
pnExceptionValue — return current exception value
void
pnExceptionValue();
pnExceptionValue() returns an object corresponding to this exception.
This function returns the object that was passed as parameter to pnExceptionSet(). If invoked when no exception or an exception for which there is no associated information was raised, a void value is returned.
pnExceptionFree() pnExceptionId() pnExceptionMajor() pnExceptionSet()
pnGetBaseURI — get base URI for MDPro
string
pnGetBaseURI();
;
pnGetBaseURI() returns the base URI of MDPro.
This function returns the base URI of MDPro.
URI is the path part of an URL, for instance in the URL 'http://www.maxdev.com/stuff/index.php' the URI would be '/stuff/index.php'.
// get base URI
$path = pnGetBaseURI();
|
pnGetBaseURL()
pnGetBaseURL — obtain base URL for this site
string
pnGetBaseURL();
pnGetBaseURL() obtains the base URL for the site. The base url is defined as the full URL for the site minus any file information i.e. everything before the 'index.php' from your start page.
This function returns the base URL of the site.
The last character in the string returned by pnGetBaseURL() is always '/'
pnGetBaseURL() replaces the old nukeurl global variable.
pnGetStatusMsg — obtain status message
string
pnGetStatusMsg();
pnGetStatusMsg() obtains the last status message posted for this session. The status message exists in one of two session variables: 'statusmsg' for a status message, or 'errormsg' for an error message. If both a status and an error message exists then the error message is returned.
This function returns the value of the last status message posted, or void if no status message exists.
pnGetStatusMsg() is a destructive function - it deletes the two session variables 'statusmsg' and 'erorrmsg' during its operation.
pnSessionSetVar()
pnInit — initialise MDPro
void
pnInit();
pnInit() initialises the MDPro system. It loads the required includes, sets up sessions and database connections, and obtains the system configuration.
pnInit() does not return a value; if the function fails somewhere it will exit.
In future pnInit() might give a return value, to make it easier to optionally include MDPro functionality in third-party scripts.
pnModAPIFunc — execute a module API function
mixed
pnModFunc(modname,
type,
func,
args);
string modname,
, string type,
, string func,
, array args
;
BAD_PARAM
MODULE_FUNCTION_NOT_EXIST
pnModFunc() calls a specific module API function.
The well-known name of a module to execute a function from
The type of function to execute; currently one of 'user' or 'admin'
The name of the module API function to execute
An associative array of arguments to pass to the module API function. The exact number and type of arguments is function-dependent.
This function returns whatever the return value of the resultant function is if it succeeds. This function returns void if an exception was raised.
This function raises BAD_PARAM if you pass an invalid parameter. This function raises MODULE_FUNCTION_NOT_EXIST if the module function doesn't exist. This function throw back exceptions raised by module function.
Before calling this function you MUST load the module API with pnModAPILoad.
For more information on well-known names of modules please refer to the documentation for pnModGetVar()
// Call News module user function getarticles with argument 'id' set to 3
$articles = pnModAPIFunc('News',
'user',
'getarticles',
array('id' => 3));
if (!isset($articles)) {
// pnModAPIFunc() failed
} elseif ($articles == false)
// getarticles failed
} else {
// getarticles succeeded, data in $articles
}
// Call Permissions admin function list with no arguments
$list = pnModAPIFunc('Permissions',
'admin',
'list');
if (!isset($list)) {
// pnModAPIFunc() failed
} elseif ($list == false)
// list failed
} else {
// list succeeded, data in $list
}
|
pnModGetVar(), pnModAPILoad(), pnModFunc()
pnModAPILoad — load a module API
int
pnModAPILoad(modname,
type);
string modname,
, string type
;
BAD_PARAM
DATABASE_ERROR
MODULE_FILE_NOT_EXIST
MODULE_NOT_EXIST
pnModAPILoad() loads extra functions into the MDPro system to extend its abilities.
The well-known name of a module to load
The type of module functions to load; currently one of 'user' or 'admin'.
This function returns true if the module loaded successfully. This function returns void if an exception was raised.
This function raises BAD_PARAM if you pass an invalid parameter. This function raises DATABASE_ERROR if an error occurs while querying data. This function raises MODULE_FILE_NOT_EXIST if a module file doesn't exist. This function raises MODULE_NOT_EXIST if the module doesn't exist.
The PostNuke API keeps track of what modules have been loaded, so multiple calls to pnModAPILoad() with the same parameters will return true each time.
This function does not load in the relevant display functionality for this module automatically, this must be carried out by a separate call to pnModLoad().
For more information on well-known names of modules please refer to the documentation for pnModGetVar()
// See if News module is available
if (pnModAvailable('News')) {
// Load the user API for the News module
if (!pnModAPILoad('News', 'user')) {
die('Could not load News module API');
}
}
|
pnModLoad(), pnModGetVar()
pnModAvailable — check if a module is available
bool
pnModAvailable(modname);
string modname
;
BAD_PARAM
DATABASE_ERROR
pnModAvailable() confirms whether a module is available to be used within the MDPro system.
The well-known name of a module to check
This function returns true if the module is available for use, false if the module is not available for use. This function returns void if an exception was raised.
This function raises BAD_PARAM if you pass an invalid parameter. This function raises DATABASE_ERROR if an error occurs while querying data.
A module that is loaded into the MDPro system but which is inactive or uninitialized is defined as not available for use.
For more information on well-known names of modules please refer to the documentation for pnModGetVar()
// See if News module is available
if (pnModAvailable('News')) {
// Load the News module
if (!pnModAPILoad('News', 'user')) {
die('Could not load News module API');
}
}
|
pnModCallHooks — carry out hook operations for module
bool
pnModCallHooks(hookobject,
hookaction,
hookid,
extrainfo);
string hookobject,
string hookaction,
string hookid,
string extrainfo
;
BAD_PARAM
DATABASE_ERROR
MODULE_FILE_NOT_EXIST
MODULE_FUNCTION_NOT_EXIST
MODULE_NOT_EXIST
pnModCallHooks() carries out hook operations for a module
the object the hook is called for - either 'item' or 'category'
the action the hook is called for - one of 'create', 'delete', 'transform', or 'display'