PostNuke: A Flexible Open Source Content Management System
home | forum | international support | contact us

Documentation Wiki

Writing a Block


Introduction

A block consists of one php file and, depending on the need for custom block configuration, one or two template files. A block must be associated with a module. Before authoring a block decide on the following information

  1. The module with which this block will be associated.
  2. A unique identifier, within the scope of the module, for the block. This is known as the 'block key' or 'bkey'.
  3. If the module will require a template to define custom settings for the block.

Creating the files structure for the block


Having decided on the requirements for this block the basic file structure can now be defined. The files needed for this block will be
  1. modules/<module>/pnblocks/<bkey>.php
  2. modules/<module>/pntemplates/<module>_<bkey>.htm
  3. modules/<module>/pntemplates/<module>_<bkey>_modify.htm if the block requires a template for custom settings.

Creating the php file


The php file for a block contains a number of functions that tell the PostNuke core about the block, how to display the block and how to handle any custom settings for the block. The functions are

  1. <module>_<bkey>block_init
  2. <module>_<bkey>block_info
  3. <module>_<bkey>block_display
  4. <module>_<bkey>block_modify if the block requires a template for custom settings.
  5. <module>_<bkey>block_update if the block requires a template for custom settings.

Writing the php code


init function


<module>_<bkey>block_init

The purpose of this function is to let the PostNuke core know about the permissions schema that this block uses to control access to it's display. For consistency it's recommend that the block key and the block title are used as the permissions schema for blocks.

function <module>_<bkey>block_init()
{
    pnSecAddSchema('<module>:<bkey>block:', 'Block title::');
}


info function


<module>_<bkey>block_info

The purpose of this function is to provide the Blocks module with information about this block. This information is then used by the blocks module to alter its behaviour when creating and editing blocks. The return from this function is a simple assoicative array containing values for a set of specifc keys.

function <module>_<bkey>block_info()
{
    return array('text_type'        => '<bkey>',
                 'module'           => '<module>',
                 'text_type_long'   => '<text description of the block>',
                 'allow_multiple'   => <boolean - true or false>,
                 'form_content'     => <boolean - true or false>,
                 'form_refresh'     => <boolean - true or false>,
                 'show_preview'     => <boolean - true or false>,
                 'admin_tableless'  => <boolean - true or false>);
}


The use of each value is
  • text_type - The type of block; Set this to the block key.
  • module - The module to which this block belong.
  • text_type_long - A description of the purpose of this block.
  • allow_multiple - Allow multiple instances of the block.
  • form_content - Display a text area allowing direct access to the 'content' field of the block. The value of this will depend on the nature of the block. For instance the html block shows this text area where as a menu block doesn't since the block content is serialized.
  • form_refresh - Use the block refresh value. This is useful for blocks that obtain data from outside sources.
  • show_preview - <todo - need to check what, if anything, this actually does....>
  • admin_tableless - Tells the blocks module that the modify template uses newer tablesless form methods.

display function


<module>_<bkey>block_display

This function is the main display function. It produces the output that the user sees for this block. As such the actual code of this block will vary depending on the block being written. There are however a number of standard pieces of code that make up this function.

function <module>_<bkey>block_display($blockinfo)
{
    // Security check (1)
    if (!SecurityUtil::checkPermission('<module>:<bkey>block:', "$blockinfo[title]::", ACCESS_READ)) {
        return false;
    }

    // Check if the module is available. (2)
    if (!pnModAvailable('<module>')) {
        return false;
    }

    // Get variables from content block (3)
    $vars = pnBlockVarsFromContent($blockinfo['content']);

    // Defaults (4)
    if (empty($vars['<yourvar>'])) {
        $vars['<yourvar>'] = <your default value for this var>;
    }

    // ..........your custom block code goes here.......... (5)

    // Create output object (6)
    $pnRender = pnRender::getInstance('<module>');

    // assign your data to to the template (7)
    $pnRender->assign(....., ......);
    $pnRender->assign(....., ......);

    // Populate block info and pass to theme (8)
    $blockinfo['content'] = $pnRender->fetch('<module>_block_<bkey<.htm');

    return themesideblock($blockinfo); (9)
}


The above annontated code shows an outline of the code that will feature in most, if not all blocks.

  1. A security check to determine if the current user is allowed to see this block.
  2. A check if the module associated with this block is available.
  3. Obtaining any block variables - this code is only necessary if your block requires any custom block variables.
  4. Defining defaults for any block variables - again this code is only necessary if your block requires any custom block variables.
  5. YOUR CODE
  6. Creating a new output object to render out block output.
  7. Assign any template variables.
  8. Obtain the output from of the template.
  9. Return the block ouput back to the core for wrapping in any theme block templates.

Although a block belongs to a module it can be displayed at any time, even when other modules are active. In this case the modules stylesheets are not loaded and the block output will render without your special css designed for this module (e.g. lists, alignments, fonts, colors etc.).

For .76x you can use this little code snippet to avoid such problems:

    // insert directly after step 6
    // load the modulestylesheet plugin to determine the stylesheet path
    require_once $pnRender->_get_plugin_filepath('function','modulestylesheet');
    $css = smarty_function_modulestylesheet(array('xhtml' => 1,
                                                  'modname' => "<module>"), $pnRender);
    global $additional_header;
    if(is_array($additional_header)) {
        if(!in_array($css, $additional_header)) {
            $additional_header[] = $css;
        }
    } else {
        $additional_header[] = $css;
    }


This will add an additional header for loading the default style.css either from the module or, if overridden, from the theme.

As .8 makes our lifes easier, the code for this version will be a simple

    // insert directly after step 6
    PageUtil::addVar('stylesheet', ThemeUtil::getModuleStylesheet('<module>'));


modify function


<module>_<bkey>block_modify

This function is called by the blocks module if the block has any custom block variables. The return from the function is part of a form containing just the controls necessary to edit this blocks custom block variables. The output of this function is inserted into the standard block modify form.

The PHP code of this function will look like

function <module>_<bkey>block_modify($blockinfo)
{
    // Get current content (1)
    $vars = pnBlockVarsFromContent($blockinfo['content']);

    // Defaults (2)
    if (empty($vars['<yourvar>'])) {
        $vars['<yourvar>'] = <your default value>;
    }

    // Create output object (3)
    $pnRender = new pnRender('<module>', false);

    // assign all block variables (4)
    $pnRender->assign($vars);

    // Return the output that has been generated by this function (5)
    return $pnRender->fetch('<module>_block_<bkey>_modify.htm');
}


  1. Obtain any current block variable settings
  2. Set default values for any block variables that aren't set already
  3. Create a new output object with caching turned off
  4. Assign all block variables to the template
  5. Return the output generated by the template back to the blocks module.

The HTML template will, depending on the number of variables and the type of form control required, look like the html code below. In this example we create a simple textbox for one block variable.

<div class="pn-adminformrow">
    <label for="<module>_<variable_name>"><!--[pnml name="_A_TEXT_LABEL"]--></label>
    <input id="<module>_<variable_name>" type="text" name="<var>" value="<!--[$<var>pnvarprephtmldisplay]-->" size="5" maxlength="5" />
</div>


update function


<module>_<bkey>block_update

This function is called by the blocks when when a site administrator has updated a block of this type. The role of this function is to read and store values for the form controls created by the modify function. The php code of this function will look like

function <module>_<bkey>block_update($blockinfo)
{
    // Get current content (1)
    $vars = pnBlockVarsFromContent($blockinfo['content']);

    // alter the corresponding variable (2)
    $vars['<your var>'] = FormUtil::getPassedValue('<your var>', <your default value>, 'POST');

    // write back the new contents (3)
    $blockinfo['content'] = pnBlockVarsToContent($vars);

    // clear the block cache (4)
    $pnRender = new pnRender('<module>');
    $pnRender->clear_cache('<module>_block_<bkey>.htm');

    return $blockinfo; (5)
}


The above annotated code performs the following functions
  1. Obtain the currently defined block variables.
  2. Read the submitted form value from the POST array and define a default if it's not present.
  3. Write the new variable values back to the block content field.
  4. Create a new output object and clear any cached pages for this block.
  5. Return the modified blockinfo array back to the blocks module for further processing.

Summary


This tutorial covers an introduction to the PostNuke blocks system and how to code a simple block. The outline functions used in this tutorial are taken from the 'first' block provided as part of ExampleDB module. Further examples of blocks performing a range of different functions and of varying levels of complexity can be found within the main PostNuke distribution.

CategoryDeveloperDocs
XML Revisions of $tag
Page history :: Last Editor [ Landseer ] :: Owner [ markwest ] ::
Valid XHTML∞ :: Valid CSS∞ :: Powered by pnWikka 1.0∞ (A wiki fork from WikkaWiki∞)
 

Main Menu

Extensions Database

Documentation

Development

Login





 


 Log in Problems?
 New User? Sign Up!

Donate to PostNuke

Donate to the PostNuke Foundation's Server Fund See the news article