Source for file actionaction.php

Documentation is available at actionaction.php

  1. <?php
  2. /**
  3. * Base class inherited by all actions from the action-triage
  4. *
  5. * @author    Stuart Prescott
  6. * @copyright  Copyright Stuart Prescott
  7. * @license    http://opensource.org/licenses/gpl-license.php GNU Public License
  8. * @version    $Id$
  9. * @package    Bumblebee
  10. * @subpackage Actions
  11. *
  12. *  path (bumblebee root)/inc/actions/actionaction.php
  13. */
  14.  
  15. /** Load ancillary functions */
  16. require_once 'inc/typeinfo.php';
  17. checkValidInclude();
  18.  
  19. /** status codes for success/failure of database actions */
  20. require_once 'inc/statuscodes.php';
  21.  
  22. /**
  23. * Base class inherited by all actions from the action-triage
  24. *
  25. * An Action is a single operation requested by the user. What action is to be performed
  26. * is determined by the action-triage mechanism in the class ActionFactory.
  27. *
  28. *
  29. * Since http is a stateless protocol, what seems like just one activity
  30. * (e.g. "edit a booking") actually includes multiple http requests
  31. * ("show the user the current values" and "sync changes to disk"). Additionally,
  32. * the one application suite will have many different things to do (e.g. edit/create
  33. * users, edit/create foobar objects). There are two approaches to this multiple
  34. * functions problem: have many .php files that are called directly by the user
  35. * for each function (i.e. links to user.php and foobar.php) but then you can end up
  36. * with a lot of repeated code in each file to control the page layout, load themes,
  37. * control login etc. Alternatively, you can use just the one index.php and include
  38. * an extra control variable in each link that decides what the script should do this time.
  39. *
  40. * In either case, it is convenient to have a standard "action" object that can be created
  41. * by some ActionFactory which then obeys a standard "action" interface to then
  42. * be used by the internals of the application.
  43. *
  44. * Typical usage:
  45. * <code>
  46. * $action = new ActionFactory($params);
  47. * $action->go();
  48. * </code>
  49. *
  50. * @abstract
  51. * @package    Bumblebee
  52. * @subpackage Actions
  53. */
  54. class ActionAction {
  55.   /**
  56.   * Authorisation object
  57.   * @var    BumblebeeAuth 
  58.   */
  59.   var $auth;
  60.   /**
  61.   * Unparsed path data from the CGI call
  62.   * @var    array 
  63.   */
  64.   var $PDATA;
  65.   /**
  66.   * Parsed input data (combined PATH data and POST data)
  67.   * @var    array 
  68.   */
  69.   var $PD;
  70.   /**
  71.   * Permit normal HTML output
  72.   *
  73.   * Allows previous output (from the HTML template) to be flushed or suppress it so
  74.   * a PDF can be output.
  75.   * @var    boolean 
  76.   */
  77.   var $ob_flush_ok = 1;
  78.   /**
  79.   * The action should be read-only; no data should be changed
  80.   * @var    boolean 
  81.   */
  82.   var $readOnly = true;
  83.   /**
  84.   * Default status messages that are returned to the user.
  85.   * @var    array 
  86.   */
  87.   var $stdmessages;
  88.  
  89.   /**
  90.   * Turn on debugging messages from the Action* classes
  91.   * @var    integer 
  92.   */
  93.   var $DEBUG=0;
  94.  
  95.   /**
  96.   * Initialising the class
  97.   *
  98.   * Variable assignment only in this constructor, the child class would normally:
  99.   * - use parent's constructor
  100.   * - parse input data
  101.   *
  102.   * @param  BumblebeeAuth $auth  Authorisation object
  103.   * @param  array $pdata   extra state data from the call path
  104.   * @return void nothing
  105.   */
  106.   function ActionAction($auth,$pdata) {
  107.     $this->auth = $auth;
  108.     $this->PDATA = $pdata;
  109.     $this->stdmessages = array(
  110.       STATUS_NOOP => '',
  111.       STATUS_OK   => T_('Operation completed successfully'),
  112.       STATUS_WARN => T_('Warnings produced during operation'),
  113.       STATUS_ERR  => T_('Error. Could not complete operation'),
  114.     );
  115.   }
  116.  
  117.   /**
  118.   * Actually perform the action that this Action* class is to perform
  119.   *
  120.   * this is an abstract class and this function <b>must</b> be overridden
  121.   *
  122.   * @return void nothing
  123.   */
  124.   function go() {
  125.   }
  126.  
  127.   /**
  128.   * Parse the input data sources
  129.   *
  130.   * @return void nothing
  131.   */
  132.   function mungeInputData() {
  133.     $this->PD = $this->PDATA;
  134. /*    foreach ($_POST as $k => $v) {
  135.       $this->PD[$k] = $v;
  136.     }*/
  137.     if (isset($this->PD['id']) && $this->PD['id'] == 'showdeleted') {
  138.       $this->PD['showdeleted'] = true;
  139.       unset($this->PD['id']);
  140.     }
  141. /*    if (isset($this->PDATA[1]) && $this->PDATA[1] !== '') {
  142.       if ($this->PDATA[1] != 'showdeleted') {
  143.         $this->PD['id'] = $this->PDATA[1];
  144.       } else {
  145.         $this->PD['showdeleted'] = true;
  146.       }
  147.     }*/
  148.     #$PD['defaultclass'] = 12;
  149.     echoData($this->PD);
  150.   }
  151.  
  152.   /**
  153.   *  Reports to the user whether an action was successful
  154.   *
  155.   *   @param integer $status   success or otherwise of action
  156.   *   @param array $messages  (optional) messages to be reported, indexed by $status
  157.   *
  158.   *    $status codes as per file statuscodes.php
  159.   */
  160.   function reportAction($status, $messages='') {
  161.     //$this->log('ActionStatus: '.$status);
  162.     #echo 'final='.$status;
  163.     if ($status == STATUS_NOOP) return '';
  164.     $message = '';
  165.     if (isset($messages[$status])) {
  166.       $message .= $messages[$status];
  167.     } else {
  168.       foreach ($messages as $code => $msg) {
  169.         if ($status & $code) {
  170.           $message .= $msg;
  171.         }
  172.       }
  173.     }
  174.     if (! $message) {
  175.       foreach ($this->stdmessages as $code => $msg) {
  176.         if ($status & $code) {
  177.           $message .= $msg;
  178.         }
  179.       }
  180.     }
  181.     if (! $message) {
  182.       $message = T_('Unknown status code. Error:').' '. $status;
  183.     }
  184.     $t = '<div class="'.($status & STATUS_OK ? 'msgsuccess' : 'msgerror').'">'
  185.          .$message
  186.          ."</div>\n";
  187.     return $t;
  188.   }
  189.  
  190.   /**
  191.   * Select which item to edit for this action
  192.   *
  193.   * @param boolean $deleted  (optional) show deleted items
  194.   * @return void nothing
  195.   */
  196.   function select($deleted=false) {
  197.   }
  198.  
  199.   /**
  200.   * Edit the selected item
  201.   *
  202.   * @return void nothing
  203.   */
  204.   function edit() {
  205.   }
  206.  
  207.   /**
  208.   * Delete the selected item
  209.   *
  210.   * @return void nothing
  211.   */
  212.   function delete() {
  213.   }
  214.  
  215.   /**
  216.   *  Generic logging function for use by all Action classes
  217.   *
  218.   *   The higher the value of $priority, the less likely the message is to
  219.   *   be output. The normal range for priority is [1-10] with messages with
  220.   *   ($priority <= $this->DEBUG) being displayed.
  221.   *
  222.   *   @param string $message  the message to be logged to the browser
  223.   *   @param integer $priority  (optional) the priority level of the message
  224.   */
  225.   function log ($message, $priority=10) {
  226.     if ($priority <= $this->DEBUG) {
  227.       echo $message."<br />\n";
  228.     }
  229.   }
  230.  
  231.   /**
  232.   * Display a message to the user explaining that the requested action cannot be
  233.   * performed as the object is "readonly".
  234.   *
  235.   * This is designed to be used with the magic token verification system that requires
  236.   * that the form that is submitted by the user contains some additional secret data that
  237.   * was provided by the installation. This is designed to prevent attacks through getting
  238.   * users to visit specially crafted URLs or to submit malicious forms.
  239.   *
  240.   * @param  string    $message    message to show to the user explaining that the action cannot be processed
  241.   * @see    http://www.debian-administration.org/articles/465
  242.   */
  243.   function readOnlyError($message=null) {
  244.     if ($message !== null) {
  245.       print $message;
  246.     } else {
  247.       printf('<div class="error">%s</div>',
  248.           T_('The requested objects are read-only as I can\'t verify the validity of the form you submitted.')
  249.         );
  250.     }
  251.   }
  252.  
  253.   /**
  254.   * Cleanse the input data of all fields except for the specifed whitelisted fields
  255.   *
  256.   * Removes all user-submitted data fields from the $ActionAction::PD array except for
  257.   * the fields that are explicitly whitelisted in the function call.
  258.   *
  259.   * @param mixed   $fields     single field name or list of fields to whitelist
  260.   */
  261.   function _dataCleanse($fields) {
  262.     if (! is_array($fields)) $fields = array($fields);
  263.     $data = $this->PD;
  264.     $this->PD = array();
  265.  
  266.     foreach ($fields as $f) {
  267.       if (isset($data[$f])) {
  268.         $this->PD[$f] = $data[$f];
  269.       }
  270.     }
  271.   }
  272.  
  273. } //class ActionAction
  274.  
  275. ?>

Documentation generated on Tue, 06 Mar 2007 10:00:27 +0000 by phpDocumentor 1.3.0