0byt3m1n1

Path: /data/applications/aps.bak/postnuke/0.764-3/standard/htdocs/modules/Example/ [ Home ]
File: pnuser.php
<?php
// $Id: pnuser.php 16726 2005-08-28 13:16:31Z markwest $
// ----------------------------------------------------------------------
// PostNuke Content Management System
// Copyright (C) 2002 by the PostNuke Development Team.
// http://www.postnuke.com/
// ----------------------------------------------------------------------
// Based on:
// PHP-NUKE Web Portal System - http://phpnuke.org/
// Thatware - http://thatware.org/
// ----------------------------------------------------------------------
// LICENSE
//
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License (GPL)
// as published by the Free Software Foundation; either version 2
// of the License, or (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// To read the license please visit http://www.gnu.org/copyleft/gpl.html
// ----------------------------------------------------------------------
/**
 * Example Module
 * 
 * The Example module shows how to make a PostNuke module. 
 * It can be copied over to get a basic file structure.
 *
 * Purpose of file:  user display functions --
 *                   This file contains all user GUI functions for the module
 *
 * @package      PostNuke_Miscellaneous_Modules
 * @subpackage   Example
 * @version      $Id: pnuser.php 16726 2005-08-28 13:16:31Z markwest $
 * @author       Jim McDonald
 * @author       The PostNuke Development Team
 * @link         http://www.postnuke.com  The PostNuke Home Page
 * @copyright    Copyright (C) 2002 by the PostNuke Development Team
 * @license      http://www.gnu.org/copyleft/gpl.html GNU General Public License
 */ 

 
/**
 * the main user function
 * 
 * This function is the default function, and is called whenever the module is
 * initiated without defining arguments.  As such it can be used for a number
 * of things, but most commonly it either just shows the module menu and
 * returns or calls whatever the module designer feels should be the default
 * function (often this is the view() function)
 * 
 * @author       The PostNuke Development Team
 * @return       output       The main module page
 */
function Example_user_main()
{
    // Security check - important to do this as early as possible to avoid
    // potential security holes or just too much wasted processing.  For the
    // main function we want to check that the user has at least overview
    // privilege for some item within this component, or else they won't be
    // able to see anything and so we refuse access altogether.  The lowest
    // level of access for administration depends on the particular module, but
    // it is generally either 'overview' or 'read'
    if (!pnSecAuthAction(0, 'Example::', '::', ACCESS_OVERVIEW)) {
        return pnVarPrepHTMLDisplay(_MODULENOAUTH);
    }

    // Create output object - this object will store all of our output so that
    // we can return it easily when required
	$pnRender =& new pnRender('Example');
	    
    // Return the output that has been generated by this function
    return $pnRender->fetch('example_user_main.htm');
}

/**
 * view items
 * 
 * This is a standard function to provide an overview of all of the items
 * available from the module.
 * 
 * @author       The PostNuke Development Team
 * @param        integer      $startnum    (optional) The number of the start item
 * @return       output       The overview page
 */
function Example_user_view($args)
{
    // Security check - important to do this as early as possible to avoid
    // potential security holes or just too much wasted processing
    if (!pnSecAuthAction(0, 'Example::', '::', ACCESS_OVERVIEW)) {
        return pnVarPrepHTMLDisplay(_MODULENOAUTH);
    }

    // Get parameters from whatever input we need.  All arguments to this
    // function should be obtained from pnVarCleanFromInput(), getting them
    // from other places such as the environment is not allowed, as that makes
    // assumptions that will not hold in future versions of PostNuke
    $startnum = pnVarCleanFromInput('startnum');

    // User functions of this type can be called by other modules.  If this
    // happens then the calling module will be able to pass in arguments to
    // this function through the $args parameter.  Hence we extract these
    // arguments *after* we have obtained any form-based input through
    // pnVarCleanFromInput().
    extract($args);

	// Define a default value for our one parameter should it not be set and then
	// ensure that our input is of the correct type. If an unsuitable value is
	// found then return an error.
    if (!isset($startnum)) {
        $startnum = 1;
    }
	if (!is_numeric($startnum)) {
        return pnVarPrepHTMLDisplay(_MODARGSERROR);
    }

    // The API function is called.  The arguments to the function are passed in
    // as their own arguments array
    $items = pnModAPIFunc('Example',
                          'user',
                          'getall',
                          array('startnum' => $startnum,
                                'numitems' => pnModGetVar('Example',
                                                          'itemsperpage')));

    // The return value of the function is checked here, and if the function
    // suceeded then an appropriate message is posted.  
    if (!$items) {
        return pnVarPrepHTMLDisplay(_EXAMPLEITEMFAILED);
    }

    // Create output object
    $pnRender =& new pnRender('Example');

    // Loop through each item and display it.
	// Note that we do NOT use pnVarPrepForDisplay, pnVarCensor or anything like
	// that here as this is left to the template to simplify the code. 
	$exampleitems = array();
    foreach ($items as $item) {
        if (pnSecAuthAction(0,
                            'Example::',
                            "$item[itemname]::$item[tid]",
                            ACCESS_OVERVIEW)) {
            $pnRender->assign($item);
            if (pnSecAuthAction(0,
    	                        'Example::',
        	                    "$item[itemname]::$item[tid]",
            	                ACCESS_READ)) {						
                $exampleitems[] = $pnRender->fetch('example_user_row_read.htm', $item['tid']);
			} else {
                $exampleitems[] = $pnRender->fetch('example_user_row_overview.htm', $item['tid']);						
			}
        }
    }

	// The items that are displayed on this overview page depend on the individual 
	// user permissions. Therefor, we can not cache the whole page.
	// The single entries are cached, though.
	$pnRender->caching=false;

	// Display the entries
    $pnRender->assign('items', $exampleitems);

	// assign the start number of the pager. This allows category display hooks to
	// be able to return back the precise location in our module
	$pnRender->assign('startnum', $startnum);

    // assign the values for the smarty plugin to produce a pager in case of there
    // being many items to display.
    //
    // Note that this function includes another user API function.  The
    // function returns a simple count of the total number of items in the item
    // table so that the pager function can do its job properly
	$pnRender->assign('pager', array('numitems'     => pnModAPIFunc('Example', 'user', 'countitems'),
	                                 'itemsperpage' => pnModGetVar('Example', 'itemsperpage')));

    // Return the output that has been generated by this function
    return $pnRender->fetch('example_user_view.htm');
}

/**
 * display item
 * 
 * This is a standard function to provide detailed informtion on a single item
 * available from the module.
 * 
 * @author       The PostNuke Development Team
 * @param        integer      $tid     the ID of the item to display
 * @return       output       The item detail page
 */
function Example_user_display($args)
{
    // Get parameters from whatever input we need.  All arguments to this
    // function should be obtained from pnVarCleanFromInput(), getting them
    // from other places such as the environment is not allowed, as that makes
    // assumptions that will not hold in future versions of PostNuke.
    list($tid,
         $objectid) = pnVarCleanFromInput('tid',
                                          'objectid');

    // User functions of this type can be called by other modules.  If this
    // happens then the calling module will be able to pass in arguments to
    // this function through the $args parameter.  Hence we extract these
    // arguments *after* we have obtained any form-based input through
    // pnVarCleanFromInput().
    extract($args);

    // At this stage we check to see if we have been passed $objectid, the
    // generic item identifier.  This could have been passed in by a hook or
    // through some other function calling this as part of a larger module, but
    // if it exists it overrides $tid
    // Where ever possible all modules should support the passing of a generic
    // object id. Many hook functions will recieve the object id (via the extrainfo
    // array) but not the actual variable reference itself thus we need all API's
    // to take the generic object id specifier. If all modules used objectid  
    // generally the interoperation of modules would be significantly
    // simplified. 
    //
    // Note that this module could just use $objectid everywhere to avoid all
    // of this munging of variables, but then the resultant code is less
    // descriptive, especially where multiple objects are being used.  The
    // decision of which of these ways to go is up to the module developer
    if (!empty($objectid)) {
        $tid = $objectid;
    }
    if (!is_numeric($tid)) {
        return pnVarPrepHTMLDisplay(_MODARGSERROR);
    }

    // Create output object - this object will store all of our output so that
    // we can return it easily when required
    $pnRender =& new pnRender('Example');
	
	// For caching reasons you must pass a cache ID. This could be done as a 
	// separate parameter to every method that uses caching (like fetch, is_cached
	// etc.) or by assigning the ID to the cache_id property like it is done in
	// this case. 
	// The item ID is appropriate to be used as the cache ID.
	$pnRender->cache_id = $tid;
	
	// check out if the contents are cached.
	// If this is the case, we do not need to make DB queries.
	// Note that we print out "cached:" in front of a chached output --
	// of course, this is here to illustrate caching and needs to be removed!
	if ($pnRender->is_cached('example_user_display.htm')) {
	   return 'cached:<br />' . $pnRender->fetch('example_user_display.htm');
	}

    // The API function is called.  The arguments to the function are passed in
    // as their own arguments array
    $item = pnModAPIFunc('Example',
                         'user',
                         'get',
                         array('tid' => $tid));

    // The return value of the function is checked here, and if the function
    // suceeded then an appropriate message is posted.  Note that if the
    // function did not succeed then the API function should have already
    // posted a failure message so no action is required
    if (!$item) {
        return pnVarPrepHTMLDisplay(_EXAMPLEITEMFAILED);
    }

    // assign bold module var to Example to we can use this to decide how to
	// display the item
    $pnRender->assign('bold', pnModGetVar('Example', 'bold'));

    // Assign details of the item.  
	// Note that we do NOT use pnVarPrepForDisplay, pnVarCensor or anything like
	// that here as this is left to the template to simplify the code. 
	// Note that $item is an associative array containing the entries name and number.
	// Instead aof assigning the corresponding contents, we could simplify the code 
	// by just assigning this associative arry directly.
    $pnRender->assign($item);
	
    // Return the output that has been generated by this function
    return $pnRender->fetch('example_user_display.htm');
}

?>