MAXdev Developers Documentation

API Command Reference

19-Oct-2005

API Command Reference

Duster

MDPro API Command Reference

Author: Marco Canini

Author: Jim McDonald

Author: John Robeson

Author: Gregor J. Rothfuss

Author: Jan Schrage

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

Overview

1.1. What is the PostNuke API?
1.2. Advantages of an API
1.3. Disadvantages of an API
1.4. Who should use this API?
1.5. Status of the API
1.6. This Document
1.7. Related Documents
1.8. Suggestions and Updates

2. API Breakdown

2.1. Users
2.2. Modules
2.3. Security
2.4. Sessions
2.5. Variables
2.6. Output
2.7. Database
2.8. Miscellaneous

3. Notes on Programming with the API

3.1. Use of void

4. API Reference

1.8. Suggestions and Updates

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.

Chapter 2. API Breakdown

Table of Contents

2.1.
2.2. Modules
2.3. Security
2.4. Sessions
2.5. Variables
2.6. Output
2.7. Database
2.8. Miscellaneous

The PostNuke API is broken down in to a number of different areas. These areas are as follows:

2.1. Users

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.

2.2. Modules

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.

2.3. Security

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.

2.4. Sessions

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.

2.5. Variables

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.

2.6. Output

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.

2.7. Database

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.

2.8. Miscellaneous

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.

Chapter 3. Notes on Programming with the API

Table of Contents

3.1.

3.1. Use of `void`

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.

Chapter 4. API Reference

Table of Contents


pnBlockLoad - load a block
pnBlockShow - set configuration variable
pnConfigGetVar - get configuration variable
pnConfigSetVar - set configuration variable
pnConfigDelVar - delete a configuration variable
pnDBGetConn - get database connection
pnDBGetTables - get database tables
pnDBInit - initialize MDPro database connection
pnExceptionFree - reset exception status
pnExceptionId - return current exception identifier
pnExceptionMajor - return current exception major number
pnExceptionSet - raise an exception
pnExceptionValue - return current exception value
pnGetBaseURI - get base URI for MDPro
pnGetBaseURL - obtain base URL for this site
pnGetStatusMsg - obtain status message
pnInit - initialize MDPro
pnModAPIFunc - execute a module API function
pnModAPILoad - load a module API
pnModAvailable - check if a module is available
pnModCallHooks - carry out hook operations for module
pnModDBInfoLoad - load database info for a module
pnModDelVar - delete a module variable
pnModFunc - execute a module function
pnModGetAdminMods - get list of administration modules
pnModGetIDFromName - get module id from name
pnModGetInfo - get module info
pnModGetName - get name of current top-level module
pnModGetUserMods - get list of user modules
pnModGetVar - get module variable
pnModLoad - load module
pnModRegisterHook - register a hook function
pnModSetVar - set module variable
pnModUnregisterHook - unregister a hook function
pnModURL - create module URL
pnRedirect - redirect to another page
pnSecAddSchema - add security schema
pnSecAuthAction - authorize attempted action
pnSessionDelVar - delete session variable
pnSessionGetVar - get session variable
pnSessionInit - initialize session
pnSessionSetup - setup session
pnSessionSetVar - set session variable
pnThemeLoad - load display theme
pnUserGetAll - get basic information on all users
pnUserGetLang - get current language
pnUserGetTheme - get current theme
pnUserGetVar - get user variable
pnUserGetVars - get all user variables
pnUserLoggedIn - check if user is logged in
pnUserLogIn - log user in
pnUserLogOut - log user out
pnUserSetVar - set user variable
pnUserValidateVar - validate user variable
pnVarCensor - remove banned words from variable
pnVarCleanFromInput - obtain form variable
pnVarPrepForDisplay - prepare variable for display
pnVarPrepForOS - prepare variable for operating system
pnVarPrepForStore - prepare variable for database storage
pnVarPrepHTMLDisplay - prepare variable for display, preserving some HTML tags
pnVarValidate - validate a variable

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.

Name

pnBlockGetInfo — get block information

Synopsis

array pnBlockGetInfo(bid); int bid ;

            BAD_PARAM
            DATABASE_ERROR
            ID_NOT_EXIST

Description

pnBlockGetInfo() returns an array of Block information.

Parameters

bid: The id of this block in the MDPro system.

bkey
title: The display title of the block
content: The container for block content. Serialized using pnBlockVarsFromContent() and pnBlockVarsToContent().
url: The url for blocks that depend on URLs, like a rss headlines block.
position: 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.
weight: The weight of the block, used for vertical placement of blocks.
active: The status of a block, '1' for active, '0' for inactive.
refresh: Indicates if a block should be refreshed. Examples would be headline blocks that fetch external content regularly.
last_update: The date and time of the last refresh of the block.
language: The language of the block.
mid: The ID of the module a block belongs to. '0' indicates a block belonging to the core.

Examples

// Get information on block
$blockinfo = pnBlockGetInfo($bid);

Name

pnBlockLoad — load a block

Synopsis

bool pnBlockLoad(modname, block); string modname, string block ;

            BAD_PARAM
            DATABASE_ERROR
            ID_NOT_EXIST
            MODULE_FILE_NOT_EXIST

Description

pnBlockLoad() loads a block into the MDPro system.

Parameters

modname: 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.
block: The name of the block to load

Return Values

This function returns true if the module loaded successfully, and void if an exception was raised.

Exceptions

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.

Notes

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().

Examples

  // Load the past article block from the News module
  if (!pnBlockLoad('News', 'past')) {
    die('Could not load past articles block');
  }

Name

pnBlockShow — set configuration variable

Synopsis

string pnBlockShow(modname, block, blockinfo); string modname, , string block, , array blockinfo ;

            BAD_PARAM
            DATABASE_ERROR
            ID_NOT_EXIST
            MODULE_FILE_NOT_EXIST

Description

pnBlockShow() gets the output of a block by calling its 'block_display' function.

Parameters

modname: 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.
block: The name of the block to load
blockinfo: An associative array of parameters to pass to the block display function. The exact number and type of parameter is block-dependent.

TODO

Name

pnConfigGetVar — get configuration variable

Synopsis

mixed pnConfigGetVar(name); string name ;

            BAD_PARAM
            DATABASE_ERROR

Description

pnConfigGetVar() obtains a configuration variable from the MDPro system.

Parameters

name: The name of the configuration variable to obtain

debug: Level of debugging required. 0 is no debugging, 1 is normal debugging.
Version_Num: Version of this MDPro system
Version_ID: ID of this MDPro system; currently always 'MDPro'
Version_Sub: Sub-ID of this MDPro system
startpage: Name of initial module for this MDPro system to load
adminmail: Email address of site administrator
sitename: Name of this MDPro system
description (formerly slogan): Description of this MDPro system
timezone_offset: Timezone offset of this MDPro system, in hours from GMT-12
seclevel: Security level of this site; one of 'high', 'medium', or 'low'
banners: Flag to state whether advertising banners are shown; '0' for no or '1' for yes
language: Code of default language for this MDPro system
locale: Locale for this MDPro system
BanMode: Flag to state whether banned is active; '0' for no or '1' for yes
BannedList: Array of words that are banned by this MDPro system

Other variables will be made available in future releases of the API.

Examples

// Get locale for this site
$locale = pnConfigGetVar('locale');

Name

pnConfigSetVar — set configuration variable

Synopsis

bool pnConfigSetVar(name, value); string name, , string value ;

            BAD_PARAM
            DATABASE_ERROR

Description

pnConfigSetVar() sets a configuration variable on the MDPro system.

Parameters

name: The name of the configuration variable to set
value: The value to set the configuration variable to

// Set locale for this site
if (!pnConfigSetVar('locale', 'en_GB')) {
    die('Error setting configuration variable');
}

Name

pnConfigDelVar — delete a configuration variable

Synopsis

bool pnConfigDelVar(name); string name ;

            BAD_PARAM
            DATABASE_ERROR

Description

pnConfigDelVar() deletes a configuration variable from the MDPro system.

Parameters

name: The name of the configuration variable to delete

// Remove locale setting
if (!pnConfigDelVar('locale')) {
  die('Error deleting configuration variable');
}

// Get database connection
list($dbconn) = pnDBGetConn();