Programming : Adding a custom block position in PostNuke

For the edification and betterment of all suffering PostNuke module coders everywhere, I hereby present a comprehensive, step-by-step guide on how to add a new block position in PostNuke.

The Goal

Several of my clients have heavy-traffic websites that have designs, the content for which cannot be accommodated by just the three standard block positions (left, right and center). In order to activate Xanthia caching, I had to figure out how to add more block positions than just the default three. It took me a while, but I think I've cracked it. This fine thread got me started, but I think the instructions could be clearer.

The new block position I wanted to add was "Top Right". This tutorial will provide instructions on how to add that block. Feel free to adapt it to your needs. We'll pretend that your theme is called MyTheme.

This tutorial assumes you're running PostNuke .764, though it probably works fine for versions in the .76x line.

Step 1: Make a new block template

In /themes/MyTheme/templates/blocks/, duplicate dsblock.htm. Call it trblock.htm. Open it up and fuss with the template if you like, or put that off until later. Here's how mine looked:

<div class="top_right_block">
    <!--[$content]-->
</div>

Upload your new template to /themes/MyTheme/templates/blocks/.

Step 2: Alter xaninit.php

I added the following lines to the xaninit.php file of my theme:

CreateThemeTemplate($skinID, 'trblock', 'trblock.htm', 'block');

and

CreateThemeZone($skinID, 'Top Right Block', 'trblock', 0, 1, 'block');

Each of these follows a long list of calls to the same function; just slap it in at the end.

After uploading xaninit.php, if you are currently using the theme in question, you'll need to deactivate it and reactivate it.

Step 3: Edit your theme configuration in Xanthia

Go to the Xanthia administration module. Click "Edit" by MyTheme. Click the Templates tab. You should see "trblock.htm" in the Block templates column. Now click the Content Wrappers tab. You should see Top Right Block amidst the "Required" content wrappers. (This property was set in the call to CreateThemeZone(); it's the <type> parameter.)

Up to now we've just confirmed that your xaninit.php file was loaded correctly. (If it wasn't, go back and check your syntax in steps 1 and 2.) Now we're going to add a Block Position Tag so you can actually place your new blocks into your theme templates.

Click the "Block Position Tags" tab. Enter "topright" for the "Tag description" and TOPRIGHTBLOCKS for the "Tag to use in theme". (Xanthia converts it to all-caps anyway - presumably to prevent you from overwriting one of the default Xanthia template variables - so you might as well avoid confusing yourself and put it in that way.) Click Submit. Now you can place the top right blocks into your theme by invoking:

<!--[$TOPRIGHTBLOCKS]-->

You may want to actually put that into your home.htm and master.htm templates, so you can test it out and jiggle with glee in Step 5.

Step 4: Create your block

Go to the Blocks administration panel and create an instance of the block you want to be a Top Right block. You will not yet be able to assign it to the top right position! Don't panic.

Step 5: Update your blocks

This step lets you specify where blocks appear and what template they use on a per-module basis. Unfortunately, it appears you have to set the custom position and template for each block for every module that you plan to use in your site. D'oh!

Go back to Xanthia admin -> [Edit link for MyTheme].
Click on the "Block Control" tab. Control-click to select the names of all the blocks you want to be in the top right slot AND THE "==Block Control" ELEMENT. (I would never have thought to do this had not Teb in the PostNuke Support Forums mentioned it in passing. Thanks Teb.)
Click the Update button. Now you will see a long list of all the modules installed in PostNuke, with your block(s) listed under each one. (You may need to click the "*" link.)
For each module you plan on using, change the position of the block to "topright", which now, miraculously, is among the position selections. (Is there a more efficient way to do this? Probably, but I don't know what it is.) To make things more inconvenient, the page will reload every time you change one of the drop-downs.
Also change the Template selection for each block (in each module you're going to use) to "trblock.htm" from "Default Template". "Default Template" appears to use the dsblock.htm template rather than the template specified for trblock in xaninit.php. Again the page load thing.

Anyway.

At this juncture, your block will appear wherever in your Xanthia templates you placed the tag you created in step 3. Assuming you followed my advice and did this, you may now jiggle with glee, and turn on Xanthia caching.

Got a question? Email me. Offers for cheap viagra will not be considered.