Module Programming Part 1

In this section we will cover the basics of how a module functions. You should be familiar with the Basic Module Structure∞ before proceeding to this stage.

Calling a Module

The PostNuke Application Framework takes standard arguments in the calling URL. It is also possible to call PostNuke modules within code, but this will be cover later. The arguments will be explained.

PostNuke run exclusively from the index.php although we do have some wrapper scripts which will be covered later.

index.php expects three arguments module, type, and func in the form

index.php?module=<module>&type=<type>&func=<func>

module

The name of the module you want to call. If not specified will default to the module specified in the PostNuke System Settings. In a standard install this is often the News module. So if you provided this link,

index.php?type=<user>&func=<view>

Postnuke would look in the News module use the file pnuser.php and call the function news_user_view().
PostNuke will know to get all files required from the module's own directory.

type

The type argument tells PostNuke which file to find the function required. In effect you tell PostNuke to include the file pn{$type}.php (in the module's own folder determined from the module argument above. If not specified, defaults to user - i.e., include pnuser.php in the module folder.

eg.

• type=user means include the file pnuser.php (default if type not specified)
• type=admin means include the file pnadmin.php
• type=test means include the file pntest.php

func

The func parameter tells PostNuke which function to call in the included file in the form {$module}_{$type}_{func}() The default value for func is 'main' if not specified.

e.g.

• func=test calls the function modulename_type_test()

Examples

Here are a number of examples to help you get a feel for how the calling process works. In your own modules you are expected to follow this scheme. It make all modules standard, so others can understand your code and allows others to call functions within your module from other modules.

1. index.php?module=helloworld&type=test&func=add
   • look in modules/helloworld
   • include pntest.php
   • call the function helloworld_test_add()
2. index.php?module=helloworld&type=user&func=show
   • look in modules/helloworld
   • include pnuser.php - (default: type=user)
   • call the function helloworld_user_show()
3. index.php?module=helloworld&type=&func=view
   • look in modules/helloworld
   • include pnuser.php
   • call the function helloworld_admin_view()
4. index.php?module=Feedback&type=admin
   • Look in modules/Feedback
   • Include pnadmin.php
   • call the function feedback_admin_main() - (default: func=main)
5. index.php?module=News
   • Look in modules/News folder
   • Include pnuser.php - (default: type=user)
   • call function news_user_main() - (default: func=main)

In summary, we can call specific functions from the URL by telling PostNuke the module name, the file type, and the function name we wish to call. We will now explore functions a little more.

Now it is time for some code. Before we can write our first function, we have some preliminary set up to do. The steps are

1. Create the new module files
2. Rename the module folder and the module name in all the files
3. Add our code to the module
4. Install and activate the module

Create the new module files

Post nuke makes this very easy. Navigate to the root directiory of your PostNuke intall and open the modules folder. Inside you will find a folder named blank. Copy this folder and name it helloworld. You now have a complete set of empty module files that can be used for creating your new module. (We will explore all the files and what they do later.)

Rename the module folder and the module name in all the files

Change the name of the folder to helloworld and use a text editor to open each file and change every instance of blank to helloworld. It would be useful to use the search and replace function to modify all these files. Every instance should be be changed, but if you miss a few, it should still work.

Add the helloworld code to the module

Module functions

Module functions should return a mixed result, or boolean: they should never echo or print anything directly (to the screen). PostNuke will take the return value of the module function and process it. PostNuke itself will render any display content. Later we will learn about pnRender and how to display content. For now we will keep it simple.

example:

Install and activate the module

Before calling the module function we have to install the module in PostNuke. The steps are:

1. Login as administrator
2. Goto Administration -> Modules
3. Regenerate the modules list from the filesystem
4. Select the new module helloworld
5. Initialize and Activate

For more information on installing modules see Installing Modules∞ in the user documentation. Once your module is activated you should be able to call this function with

http://mydomain.com/index.php?module=helloworld∞

Since we have not specified type or func, PostNuke will assume type=user and func=main

PostNuke will now display 'hello world!' Notice how it's rendered with all the rest of the page content.

Next Step: Module Programming Part 2

DeveloperDocs

---

CategoryDeveloperDocs