Source for file choicelist.php

Documentation is available at choicelist.php

  1. <?php
  2. /**
  3. * a choice list field from which a select, list of hrefs etc can be built
  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. /** parent object */
  18. require_once 'field.php';
  19. /** formatter helper object */
  20. require_once 'outputformatter.php';
  21. /** list (db) object */
  22. require_once 'dbchoicelist.php';
  23. /** list (non-db) object */
  24. require_once 'arraychoicelist.php';
  25.  
  26. /**
  27. * a choice list field from which a select, list of hrefs etc can be built
  28. *
  29. * A field class that can only take a restricted set of values, such as
  30. * a radio list or a drop-down list.
  31. *
  32. * This class cannot adequately represent itself and is designed to be
  33. * inherited by a representation (such as RadioList or DropDownList)
  34. * @package    Bumblebee
  35. * @subpackage FormsLibrary
  36. */
  37. class ChoiceList extends Field {
  38.   /** @var DBChoiceList  contains the DBChoiceList object which has the restricted choices */
  39.   var $list;
  40.   /** @var array         array of OutputFormatter objects  */
  41.   var $formatter;
  42.   /** @var integer       name of the id field for the value of the field */
  43.   var $formatid;
  44.   /** @var boolean       additional items can be added to the choicelist */
  45.   var $extendable = 0;
  46.   /** @var tristate      in filling list, include only deleted=true, deleted=false or both (true, false, NULL) */
  47.   var $deleted=false; //deleted=true/false in SQL; NULL means don't restrict
  48.  
  49.   
  50.   /**
  51.   *  Create a new choice list
  52.   *
  53.   * @param string $name   the name of the field (db name, and html field name
  54.   * @param string $description  used in the html title or longdesc for the field
  55.   */
  56.   function ChoiceList($name, $description='') {
  57.     parent::Field($name, '', $description);
  58.     //$this->DEBUG=10;
  59.   }
  60.  
  61.   /**
  62.   * Create a DBList object within this class that is connected to the
  63.   * available choices in the database and will handle the actual parsing
  64.   * of user input etc
  65.   *
  66.   * If php supported multiple inheritance, then $this->list would not be
  67.   * a member of the class, rather DBList would be multiply inherited along
  68.   * with Field.
  69.   *
  70.   * @param string $table the name of the DB table to query
  71.   * @param mixed $fields array or string specifying the field(s) to query
  72.   * @param string $restriction a restriction that will be applied to the query (WHERE...)
  73.   * @param string $order the order to display the results (ORDER BY...)
  74.   * @param string $idfield the name of the field that will be used to identify the selected item (value=)
  75.   * @param string $limit limits that will be applied to the query (LIMIT...)
  76.   * @param string $join any tables that should be LEFT JOINed in the query to make sense of it
  77.   * @param boolean $distinct return only DISTINCT rows (default: false)
  78.   *
  79.   */
  80.   function connectDB($table, $fields='', $restriction='', $order='name',
  81.                       $idfield='id', $limit='', $join='', $distinct=false) {
  82.     $this->list = new DBChoiceList($table, $fields, $restriction, $order,
  83.                       $idfield, $limit, $join, $distinct, $this->deleted);
  84.   }
  85.  
  86.   /**
  87.   * Provides a set of values for the droplist rather than filling it from a db query
  88.   *
  89.   * cf. ChoiceList::connectDB
  90.   *
  91.   * @param array $list List of label=>value pairs
  92.   */
  93.   function setValuesArray($list, $idfield='id', $valfield='iv'){
  94.     $this->list = new ArrayChoiceList($list, $idfield, $valfield);
  95.   }
  96.  
  97.   function text_dump() {
  98.     return $this->list->text_dump();
  99.   }
  100.  
  101.   function display() {
  102.     return $this->text_dump();
  103.   }
  104.  
  105.   /**
  106.   * Create a set of OutputFormatter objects to handle the display of this object.
  107.   *
  108.   *  called as: setFormat($id, $f1, $v1, $f2, $v2, ...) {
  109.   *    - f1, v1 etc must be in pairs.
  110.   *    - f1 is an sprintf format (see PHP manual)
  111.   *    - v1 is an array of array indices that will be used to fill the
  112.   *      fields in the sprintf format from a $data array passed to the
  113.   *      formatter when asked to display itself
  114.   */
  115.   function setFormat() {
  116.     $argc = func_num_args();
  117.     $argv = func_get_args();
  118.     $this->formatid = $argv[0];
  119.     $this->formatter = array();
  120.     for ($i = 1; $i < $argc; $i+=2) {
  121.       $this->formatter[] = new OutputFormatter($argv[$i], $argv[$i+1]);
  122.     }
  123.   }
  124.  
  125.   /**
  126.   * A test text-based format function for the object.
  127.   *
  128.   * @param array $data the data to be formatted by this object's formatter object
  129.   * @return string text-based representation
  130.   */
  131.   function format($data) {
  132.     $s = $data[$this->formatid] .":". $this->formatter[0]->format($data)
  133.         ."(". $this->formatter[1]->format($data).")";
  134.     return $s;
  135.   }
  136.  
  137.   /**
  138.   * Display the field inside a table
  139.   *
  140.   * @param integer $cols the number of columns to include in the table (extras are padded out)
  141.   * @return string a single row HTML representation of the field
  142.   */
  143.   function displayInTable($cols=3) {
  144.     if (! $this->hidden) {
  145.       $errorclass = ($this->isValid ? "" : "class='inputerror'");
  146.       $t = "<tr $errorclass><td>{$this->description}</td>\n"
  147.           ."<td title='{$this->description}'>";
  148.       if ($this->editable) {
  149.         $t .= $this->selectable();
  150.       } else {
  151.         $t .= $this->selectedValue();
  152.         $t .= "<input type='hidden' name='{$this->name}' value='{$this->value}' />";
  153.       }
  154.       $t .= "</td>\n";
  155.       for ($i=0; $i<$cols-2; $i++) {
  156.         $t .= "<td></td>";
  157.       }
  158.       $t .= "</tr>";
  159.       return $t;
  160.     }
  161.   }
  162.  
  163.   function selectedValue() {
  164.     return $this->list->selectedValue();
  165.   }
  166.  
  167.   /**
  168.   * Update the value of the field and also the complex field within based on the user data.
  169.   *
  170.   * This does *not* create new elements within the complex field (list)
  171.   * at this stage: that is deferred until the latest possible point
  172.   * for all error checking to be performed.
  173.   *
  174.   * @param array $data a set of name => value pairs from which the value of this field
  175.   *               will be extracted
  176.   * @return boolean did the field change?
  177.   */
  178.   function update($data) {
  179.     parent::update($data);
  180.     $this->list->editable = $this->editable;
  181.     $this->list->extendable = $this->extendable;
  182.     #echo "ID=".$this->list->id;
  183.     if ($this->changed) {
  184.       $this->log('haschanged');
  185.       // only update the list if things have changed
  186.       $this->list->update($this->value, $data);
  187.       $this->changed = $this->list->changed;
  188.       $this->isValid = $this->list->isValid;
  189.     }
  190.     $this->log('ChoiceList::Update->isValid= '.$this->isValid);
  191.     #Field::set($this->list->id);
  192.     #echo $this->list->id;
  193.     #echo " (nv: $this->value)";
  194.     return $this->changed;
  195.   }
  196.  
  197.   /**
  198.   * Set the value of this field, both in the Field and in the DBList
  199.   * @param string $value  value to be set
  200.   */
  201.   function set($value) {
  202.     $this->list->set($value);
  203.     parent::set($value);
  204.   }
  205.  
  206.   /**
  207.    * Check the validity of the data.
  208.    *
  209.    * Return TRUE iff the DBList isValid and the Field isValid.
  210.    * This permits two rounds of checks on the data to be performed.
  211.    *
  212.    * @return boolean the field's current value is valid?
  213.    */
  214.   function isValid() {
  215.     $this->log('ChoiceList::isValid='.$this->isValid);
  216.     return $this->isValid && Field::isValid();
  217.   }
  218.  
  219.   /**
  220.   * Obtain the SQL data necessary for including the foreign key in
  221.   * the DBRow to which we belong.
  222.   * trip the complex field within us to sync(), which allows us
  223.   * to then know our actual value (at last).
  224.   *
  225.   * @param boolean $force force the field to return a name=value statement even
  226.   *                if it would prefer not to
  227.   * @return string name='value' from parent class
  228.   */
  229.   function sqlSetStr($name='', $force=false) {
  230.     #echo "Choicelist::sqlSetStr";
  231.     $this->oob_status = $this->list->sync();
  232.     //preDump($this->list);
  233.     $this->oob_errorMessage = $this->list->oob_errorMessage;
  234.     $this->value = $this->list->id;
  235.     #preDump($this);
  236.     return Field::sqlSetStr($name, $force);
  237.   }
  238.  
  239.   /**
  240.   * prepends a value to the dropdown list
  241.   *
  242.   * @param array $a see DBChoiceList for details
  243.   */
  244.   function prepend($a) {
  245.     // templist is a horrible hack around a PHP 4.3 bug
  246.     // This is all we want to do:
  247.     //    $this->list->prepend($a);
  248.     // but that causes $this->list to suddenly become a reference: Object not &Object (see a var_dump)
  249.     // see http://bugs.php.net/bug.php?id=24485 and http://bugs.php.net/bug.php?id=30787
  250.     // Note that PHP 4.4.x claims to have fixed this bug. (although 4.4.0 does not)
  251. /*    $templist = $this->list;
  252.     $templist->prepend($a);
  253.     $this->list = $templist;*/
  254.     $this->list->prepend($a);
  255.   }
  256.  
  257.   /**
  258.   * appends a value to the dropdown list
  259.   *
  260.   * @param array $a see DBChoiceList for details
  261.   */
  262.   function append($a) {
  263.     // templist is a horrible hack around a PHP 4.3 bug, see above
  264.     // This is all we want to do:
  265.     //    $this->list->append($a);
  266. /*    $templist = $this->list;
  267.     $templist->append($a);
  268.     $this->list = $templist;*/
  269.     $this->list->append($a);
  270.   }
  271.  
  272.   /**
  273.   * set the default value for this object
  274.   */
  275.   function setDefault($val) {
  276.     // templist is a horrible hack around a PHP 4.3 bug, see above
  277.     // This is all we want to do:
  278.     //    $this->list->setDefault($val);
  279.     $this->defaultValue = $val;
  280. /*    $templist = $this->list;
  281.     $templist->setDefault($val);
  282.     $this->list = $templist;*/
  283.     $this->list->setDefault($val);
  284.   }
  285.  
  286.   function getValue() {
  287.     return (isset($this->value) ? $this->value : $this->defaultValue);
  288.   }
  289.  
  290.   /**
  291.   * PHP5 clone method
  292.   *
  293.   * PHP5 clone statement will perform only a shallow copy of the object. Any subobjects must also be cloned
  294.   */
  295.   function __clone() {
  296.     parent::__clone();
  297.     // Force a copy of contents of $this->list
  298.     if (is_object($this->list)) $this->list = clone($this->list);
  299.     foreach ($this->formatter as $k => $f) {
  300.       $this->formatter[$k] = clone($f);
  301.     }
  302.   }
  303.  
  304.  
  305. } // class ChoiceList

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