Notes on Developing Modules

Use pnAPI

pnAPI is the PostNuke Application Programming Interface, a way for modules to interact with the PostNuke core without needing to access tables and internal structures directly. The API also allows for the underlying implementation details of PostNuke to be hidden from developer so that they can write modules in a standard fashion and not worry about what might change under the hood. This is very important for a system such as PostNuke which has undergone, and continues to undergo, radical changes in the core design to allow it to be faster, more secure, and more flexible.

pnAPI is the only supported way of accessing core information. Module developers must use these methods of obtaining information from the PostNuke core system; failure to do so will very likely result in their module not working when the next version of PostNuke is released.

Security

Security is a very important part of PostNuke. All modules should subscribe to the PostNuke Security model to ensure that they operate correctly within all environments.

Variable Handling

All variables that come in to or go out of PostNuke should be handled by the relevant pnVar*() functions to ensure that they are safe. Failure to do this could result in opening security wholes at either the web, filesystem, display, or database layers. Full information on these functions is given in the PostNuke API Guide, and examples of their use are shown throughout the template module.

It can be assumed that any variables passed to functions in the PostNuke API will be handled correctly, and as such these variables do not need to be prepared with the pnVar*() functions.

Authorisation

All items displayed for users and actions carried out by administrators must be authorised through use of the pnSecAuthAction() function. This function underlies the entire PostNuke permissions system and as such must be used wherever an access check is required.

Reserved Variable Names

PostNuke has a number of variables which are reserved. These variables should not be used within modules as they can conflict with the PostNuke core and cause unpredictable results.

The current list of variables which are reserved are as follows:

        file
        func
        loadedmod
        module
        name
        op
        pagerstart
        pagertotal
        type

In addition, all one-letter variables are reserved.

Page Path

All input from webpages goes through a two-stage process. The first part is displaying the information to be entered in a form, and the second is obtaining that information and passing it on to the module API. In addition to the visible information, there is often a number of hidden items of information in the first page that is used in the second page. To ensure that any attempt to add, delete, or change information in the PostNuke system goes through the full two-stage method of gathering and processing the information the two functions pnSecGenAuthKey() and pnSecConfirmAuthKey() must be used in the appropriate places. The Template module in the standard PostNuke distribution contains a number of functions that use these API calls, and care should be taken to note where they are used so that developed modules will have the same level of protection against fraudulent administrator requests.

Output

All output generated by module functions must be returned to the PostNuke core. No output of any type should be made directly from the module; doing this is not supported and will break in future versions of PostNuke.

Using OO Code

Modules can be written as classes if desired, however the API as described in the rest of this document must still be adhered to. The simplest way of doing this is to use compatibility functions, for example:

function mymod_user_main()
{
    // Instantiate 
    $obj = new myClass();
    // Call relevant method and return output
    return $obj->usermain();
}