Source for file field.php

Documentation is available at field.php

  1. <?php
  2. /**
  3. * database primitive object for an individual field within a row
  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 FormsLibrary
  11. */
  12.  
  13. /** Load ancillary functions */
  14. require_once 'inc/typeinfo.php';
  15. checkValidInclude();
  16.  
  17. /** type checking and data manipulation */
  18. require_once 'validtester.php';
  19. /** status codes for success/failure of database actions */
  20. require_once 'inc/statuscodes.php';
  21.  
  22. /**
  23. * Field object that corresponds to one field in a SQL table row.
  24. *
  25. * A number of fields would normally be held together in a DBRow,
  26. * with the DBRow object controlling the updating to the SQL database.
  27. *
  28. * Typical usage is through inheritance, see example for DBRow.
  29. * <code>
  30. *     $f = new TextField("name", "Name");
  31. * </code>
  32. *
  33. * @package    Bumblebee
  34. * @subpackage FormsLibrary
  35. */
  36. class Field {
  37.   /** @var string   name of this field */
  38.   var $name;
  39.   /** @var string   label for the field in the display */
  40.   var $longname;
  41.   /** @var string   description for the field in the mouse-over */
  42.   var $description;
  43.   /** @var boolean  field is required */
  44.   var $required = 0;
  45.   /** @var string   value of this field */
  46.   var $value;
  47.   /** @var string   previous value of this field*/
  48.   var $ovalue;
  49.   /** @var string   default value of the field */
  50.   var $defaultValue = '';
  51.   /** @var string   duplicate the value of this field (when hidden) in a hidden field with this name  */
  52.   var $duplicateName;
  53.   /** @var tristate  this field is editable */
  54.   var $editable = -1;
  55.   /** @var string   the value of this field has changed */
  56.   var $changed = 0;
  57.   /** @var string   the field is a hidden widget */
  58.   var $hidden;
  59.   /** @var string   the data contained by the field is valid */
  60.   var $isValid = 1;
  61.   /** @var string   if the ID changes, then notify descendents */
  62.   var $notifyIdChange = 0;
  63.   /** @var tristate   don't to validation on this field */
  64.   var $suppressValidation = -1;
  65.   /** @var boolean  permit NULL values in this field */
  66.   var $useNullValues = 0;
  67.   /** @var array    display attributes */
  68.   var $attr = array();
  69.   /** @var string   CSS class to be used for marking fields with errors */
  70.   var $errorclass = 'error';
  71.   /** @var string   prepended to the name of the field in the html id and hence in the data array */
  72.   var $namebase;
  73.   /** @var string   function to call to check that the data is valid */
  74.   var $isValidTest = 'isset';
  75.   /** @var string   function to call to clean the data string before testing if valid */
  76.   var $valueCleaner = null;
  77.   /** @var boolean  don't generate an SQL name=value representation for this field  */
  78.   var $sqlHidden = 0;
  79.   /** @var boolean  this field requires two-stage sync */
  80.   var $requiredTwoStage = 0;
  81.   /** @var string   status code of the descendents of this field (out-of-band data reporting) */
  82.   var $oob_status = STATUS_NOOP;
  83.   /** @var string   error message from this field or its descendents */
  84.   var $oob_errorMessage = '';
  85.   /** @var integer  debug log level */
  86.   var $DEBUG = 0;
  87.  
  88.   /**
  89.   *  Create a new generic field object, designed to be superclasses
  90.   *
  91.   * @param string $name   the name of the field (db name, and html field name
  92.   * @param string $longname  long name to be used in the label of the field in display
  93.   * @param string $description  used in the html title or longdesc for the field
  94.   */
  95.   function Field($name, $longname='', $description='') {
  96.     $this->name = $name;
  97.     $this->longname = $longname;
  98.     $this->description = $description;
  99.   }
  100.  
  101.   /**
  102.   * update the value of the object with the user-supplied data in $data
  103.   *
  104.   * $data is most probably from POST data etc.
  105.   *
  106.   * The validity of the data is *not* checked at this stage, the object
  107.   * only takes the user-supplied value.
  108.   *
  109.   * $data is an array with the data relevant to this field being
  110.   * in the key $this->namebase.$this->name.
  111.   *
  112.   * For example:
  113.   * <code>
  114.   * $this->namebase = 'person-';
  115.   * $this->name     = 'phonenumber';
  116.   * $data['person-phonenumber'] // used for the value
  117.   * </code>
  118.   *
  119.   * @param array $data is name => value pairs as above
  120.   * @return boolean  did the value of this object change?
  121.   */
  122.   function update($data) {
  123.     if (isset($data["$this->namebase$this->name"]) || $this->useNullValues) {
  124.       $newval = issetSet($data, "$this->namebase$this->name");
  125.       $this->log("$this->name, $this->value, $newval ($this->useNullValues)");
  126.       if (isset($this->valueCleaner) && is_callable($this->valueCleaner)) {
  127.         $newval = call_user_func($this->valueCleaner, $newval);
  128.       }
  129.  
  130.       if ($this->editable) {
  131.         // we ignore new values if the field is not editable
  132.         if ($this->changed = ($this->getValue() != $newval)) {
  133.           $this->ovalue = $this->getValue();
  134.           $this->value = $newval;
  135.         }
  136.       } else {
  137.         //ensure that the value is copied in from the default value if
  138.         //it is unset.
  139.         $this->value = $this->getValue();
  140.       }
  141.     } else {
  142.       if ($this->getValue() != $this->value) {
  143.         $this->changed = 0;
  144.         $this->value = $this->getValue();
  145.       }
  146.     }
  147.     $this->log($this->name . ($this->changed ? ' CHANGED' : ' SAME'));
  148.     return $this->changed;
  149.   }
  150.  
  151.   /**
  152.   * Check the validity of the current data value.
  153.   *
  154.   * This also checks the validity of the data even if the data is not newly-entered.
  155.   * Returns true if the specified validity tests are passed:
  156.   *  -   is the field required to be filled in && is it filled in?
  157.   *  -   is there a validity test && is the data valid?
  158.   *
  159.   * @return boolean  is the data value valid
  160.   */
  161.   function isValid() {
  162.      $this->isValid = 1;
  163.     if ($this->required) {
  164.       #$this->isValid = (isset($this->value) && $this->value != "");
  165.       $this->isValid = ($this->getValue() != '');
  166.       $this->log($this->name . ' Required: '.($this->isValid ? ' VALID' : ' INVALID'));
  167.     }
  168.     if ($this->isValid && $this->suppressValidation == 0) {
  169.       $this->isValid = ValidTester($this->isValidTest, $this->getValue(), $this->DEBUG);
  170.     }
  171.     $this->log($this->name . ($this->isValid ? ' VALID' : ' INVALID'));
  172.     return $this->isValid;
  173.   }
  174.  
  175.   /**
  176.   * set the value of this field
  177.   *
  178.   * <b>without</b> validation or checking to see whether the field has changed.
  179.   *
  180.   * @param string   the new value for this field
  181.   */
  182.   function set($value) {
  183.     //echo "Updating field $this->name. New value=$value\n";
  184.     $this->value = $value;
  185.   }
  186.  
  187.   /**
  188.   * create an SQL-injection-cleansed string for db statements
  189.   *
  190.   * Generates a string that represents this field that can be used in an SQL
  191.   * UPDATE or INSERT statement. i.e. "name='Stuart'".
  192.   *
  193.   * @param string  optional SQL name to use to change the default
  194.   * @param boolean optional force the generation of the command
  195.   * @return string  in SQL assignable form
  196.   */
  197.   function sqlSetStr($name='', $force=false) {
  198.     if (! $this->sqlHidden) {
  199.       if (empty($name)) {
  200.         $name = $this->name;
  201.       }
  202.       return $name .'='. qw($this->getValue());
  203.     } else {
  204.       return '';
  205.     }
  206.   }
  207.  
  208.   /**
  209.   * Set display attributes for the field.
  210.   *
  211.   * the attribute fielde are parsed differently for each different field subclass
  212.   *
  213.   * @param array $attrs attribute_name => value
  214.   * @access public
  215.   */
  216.   function setattr($attrs) {
  217.     if (! is_array($attrs)) return;
  218.     $this->attr = array_merge($this->attr, $attrs);
  219.   }
  220.  
  221.   /**
  222.   * Quick and dirty display of the field status
  223.   *
  224.   * @return string simple text representation of the class's value and attributes
  225.   */
  226.   function text_dump() {
  227.     $t  = "$this->name =&gt; ".$this->getValue();
  228.     $t .= ($this->editable ? "(editable)" : "(read-only)");
  229.     $t .= ($this->isValid ? "" : "(invalid)");
  230.     $t .= "\n";
  231.     return $t;
  232.   }
  233.  
  234.   /**
  235.   * Generic display function
  236.   */
  237.   function display() {
  238.     return $this->text_dump();
  239.   }
  240.  
  241.   /**
  242.   * html representation of this field as a "hidden" form widget
  243.   */
  244.   function hidden() {
  245.     return "<input type='hidden' name='$this->namebase$this->name' "
  246.            ."value='".xssqw($this->getValue())."' />";
  247.   }
  248.  
  249.   /**
  250.   * render this form widget in an html table
  251.   *
  252.   * @param integer $cols  number of columns to be included in table (padding cols will be added)
  253.   * @abstract
  254.   */
  255.   function displayInTable($cols=3) {
  256.   }
  257.  
  258.   /**
  259.   * return the current value as text and the widget as a hidden form element
  260.   *
  261.   * @return string current value
  262.   * @abstract
  263.   */
  264.   function selectedValue() {
  265.   }
  266.  
  267.   /**
  268.   * return an html representation of the widget
  269.   *
  270.   * @return string html widget
  271.   * @abstract
  272.   */
  273.   function selectable() {
  274.   }
  275.  
  276.   /**
  277.   * Obtain the value of the field, taking account of default values
  278.   *
  279.   * @return mixed field value
  280.   */
  281.   function getValue() {
  282.     //echo "FIELD $this->name: ".$this->value.":".$this->defaultValue."<br />";
  283.     return (isset($this->value) ? $this->value : $this->defaultValue);
  284.   }
  285.  
  286.   /**
  287.   * set whether this field is editable or not
  288.   *
  289.   * @param boolean $editable  new editable state
  290.   */
  291.   function setEditable($editable=1) {
  292.     $this->editable = $editable;
  293.   }
  294.  
  295.   /**
  296.   * set the namebase for the data storage in the html form
  297.   *
  298.   * @param boolean $editable  new editable state
  299.   */
  300.   function setNamebase($namebase='') {
  301.     $this->namebase = $namebase;
  302.   }
  303.  
  304.   /**
  305.   * Generic logging function
  306.   *
  307.   * @param string $logstring   data to log
  308.   * @param integer $priority   log level for this message
  309.   */
  310.   function log($logstring, $priority=10) {
  311.     if ($priority <= $this->DEBUG) {
  312.       echo $logstring."<br />\n";
  313.     }
  314.   }
  315.  
  316.   /**
  317.   * PHP5 clone method
  318.   *
  319.   * PHP5 clone statement will perform only a shallow copy of the object. Any subobjects must also be cloned
  320.   */
  321.   function __clone() {
  322.     // Force a copy of contents of $this->list
  323.     //echo "Cloning field";
  324.     if (is_object($this->attr)) $this->attr = clone($this->attr);
  325.   }
  326.  
  327. } // class Field
  328.  
  329. ?>

Documentation generated on Tue, 06 Mar 2007 10:01:32 +0000 by phpDocumentor 1.3.0