Source for file joindata.php

Documentation is available at joindata.php

  1. <?php
  2. /**
  3. * an object that manages data related by an SQL JOIN but pretends to be a single form field.
  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. /** database row manipulation object */
  20. require_once 'dbrow.php';
  21. /** connect to database */
  22. require_once 'inc/db.php';
  23.  
  24. /**
  25. * an object that manages data related by an SQL JOIN but pretends to be a single form field.
  26. *
  27. * If the element in the table is a selection list then the setup will be
  28. * as a join table.
  29. *
  30. * We respect the 'field' interface while overriding pretty much all of it.
  31. *
  32. * Primitive class for managing join data. Can be used on its own to just
  33. * join data or with a selection lists class to make a join table.
  34. * This may be used to determine the choices
  35. * that a user is permitted to select (e.g. dropdown list or radio buttons)
  36. *
  37. * Used in a many:many or many:1 relationships (i.e. a field in a
  38. * table that is the listed in a join table
  39. *
  40. * Typical usage:<code>
  41. *   $f = new JoinData('jointable', 'id1', $table1_key, 'fieldname', 'label1');
  42. *   $f2 = new DropList('id2', 'label2');
  43. *   $f2->connectDB('table2', array('id', 'name'));
  44. *   $f2->list->prepend(array('-1','(none)'));
  45. *   $f2->setFormat('id', '%s', array('name'), ' (%s)', array('longname'));
  46. *   $f->addElement($f2);
  47. *   $f3 = new TextField('field3', '');
  48. *   $f->addElement($f3, 'sum_is_100');
  49. *   $f->joinSetup('id2', array('total' => 3));
  50. *   $f->use2StepSync = 1;
  51. * </code>
  52. * @package    Bumblebee
  53. * @subpackage FormsLibrary
  54. */
  55. class JoinData extends Field {
  56.   /** @var string   name of the join table (table has columns of form (LeftID, RightID) to join Left and Right tables */
  57.   var $joinTable;
  58.   /** @var string   column name in the join table for the column with keys/Ids from the left table */
  59.   var $jtLeftIDCol;
  60.   /** @var string   value of the left column ID that we are matching */
  61.   var $jtLeftID;
  62.   /** @var string   column name in the join table for the column with keys/Ids from the right table */
  63.   var $jtRightIDCol;
  64.   /** @var DBRow    prototype DBRow object that is replicated for each entry in the join table (1:many join) */
  65.   var $protoRow;
  66.   /** @var array    list of DBRow objects for each row returned in a 1:many join */
  67.   var $rows;
  68.   /** @var string   number of columns that this field should span in the table */
  69.   var $colspan;
  70.   /** @var array    formatting control arguments (e.g. maximum number permitted in 1:many) */
  71.   var $format;
  72.   /** @var integer  number of rows in the join */
  73.   var $number = 0;
  74.   /** @var array    list of columns to return when the containing object asks for the SQL column=value sequence */
  75.   var $reportFields = array();
  76.   /** @var array    list of functions that should be applied to the group of results collectively to test validity */
  77.   var $groupValidTest;
  78.   /** @var boolean  SQL errors should be fatal (die()) */
  79.   var $fatalsql = 0;
  80.  
  81.   /**
  82.   *  Create a new joindata object
  83.   *
  84.   * @param string $jointable    see $this->joinTable
  85.   * @param string $jtLeftIDCol  see $this->jtLeftIDCol
  86.   * @param string $jtLeftID     see $this->jtLeftID
  87.   * @param string $name   the name of the field (db name, and html field name
  88.   * @param string $description  used in the html title or longdesc for the field
  89.   */
  90.   function JoinData($joinTable, $jtLeftIDCol, $jtLeftID,
  91.                      $name, $description='') {
  92.     //$this->DEBUG=10;
  93.     $this->Field($name, '', $description);
  94.     $this->joinTable = $joinTable;
  95.     $this->jtLeftIDCol = $jtLeftIDCol;
  96.     $this->jtLeftID = $jtLeftID;
  97.     $this->protoRow = new DBRow($joinTable, $jtLeftID, $jtLeftIDCol);
  98.     $field = new Field($jtLeftIDCol);
  99.     $field->defaultValue = $jtLeftID;
  100.     $this->protoRow->addElement($field);
  101.     $this->protoRow->editable = 1;
  102.     $this->protoRow->autonumbering = 0;
  103.     $this->rows = array();
  104.     $this->groupValidTest = array();
  105.     $this->notifyIdChange = 1;
  106.   }
  107.  
  108.   /**
  109.   * Connect the join table and fill from the database
  110.   *
  111.   * @param string $jtRightIDCol  see $this->jtRightIDCol
  112.   * @param mixed  $format        see $this->format (string is converted to array)
  113.   */
  114.   function joinSetup($jtRightIDCol, $format='') {
  115.     $this->jtRightIDCol = $jtRightIDCol;
  116.     $this->format = (is_array($format) ? $format : array($format));
  117.     $this->_fill();
  118.     //preDump($this);
  119.   }
  120.  
  121.   /**
  122.   * Calculate the maximum number of rows to display (e.g. including spares)
  123.   */
  124.   function _calcMaxNumber() {
  125.     if (isset($this->format['total'])) {
  126.       $this->number = $this->format['total'];
  127.       return;
  128.     }
  129.     $this->number = $this->_countRowsInJoin();
  130.     if (isset($this->format['minspare'])) {
  131.       $this->number += $this->format['minspare'];
  132.       return;
  133.     }
  134.     if (isset($this->format['matrix'])) {
  135.       $this->number = $this->protoRow->fields[$this->jtRightIDCol]->list->length;
  136.       return;
  137.     }
  138.   }
  139.  
  140.   /**
  141.   * add a field to the join table
  142.   * Field will appear in each row returned from the join table
  143.   * @param Field  $field            the field to be added
  144.   * @param string  $groupValidTest  data validation routine for this field
  145.   */
  146.   function addElement($field, $groupValidTest=NULL) {
  147.     $this->protoRow->addElement($field);
  148.     $this->groupValidTest[$field->name] = $groupValidTest;
  149.   }
  150.  
  151.   /**
  152.   * Create a new row from the protorow for storing data
  153.   * @param integer  $rowNum   number of this row (used as unique identifier in the namebase)
  154.   */
  155.   function _createRow($rowNum) {
  156.     #echo "NAMEBASE={$this->namebase}";
  157.     #echo "NAME={$this->name}";
  158.     $this->rows[$rowNum] = clone($this->protoRow);
  159.     $this->rows[$rowNum]->setNamebase($this->namebase.$this->name.'-'.$rowNum.'-');
  160.  
  161.     #for ($i=0; $i<=$rowNum; $i++) {
  162.     #  echo "NB = ". $this->rows[$i]->namebase."<br />";
  163.     #}
  164.   }
  165.  
  166.   /**
  167.   * Fill from the database
  168.   */
  169.   function _fill() {
  170.     $this->_fillFromProto();
  171.   }
  172.  
  173.   /**
  174.   * Fill from the database one row at a time
  175.   */
  176.   function _fillFromProto() {
  177.     $oldnumber = $this->number;
  178.     $this->_calcMaxNumber();
  179.     $this->log('Extending rows from '.$oldnumber.' to '.$this->number);
  180.     for ($i=$oldnumber; $i < $this->number; $i++) {
  181.       $this->_createRow($i);
  182.       $this->rows[$i]->recNum = 1;
  183.       $this->rows[$i]->recStart = $i;
  184.       $this->rows[$i]->fill();
  185.       $this->rows[$i]->restriction = $this->jtRightIDCol .'='. qw($this->rows[$i]->fields[$this->jtRightIDCol]->value);
  186.       $this->rows[$i]->insertRow = ! ($this->rows[$i]->fields[$this->jtRightIDCol]->value > 0);
  187.       $this->log('This row flagged with insertRow '.$this->rows[$i]->insertRow);
  188.       if ($this->rows[$i]->insertRow) {
  189.         $this->rows[$i]->fillWithDefaults();
  190.       }
  191.     }
  192.     //preDump($this->rows);
  193.   }
  194.  
  195.   function display() {
  196.     //check how many fields we need to have (again) as we might have to show more this time around.
  197.     $this->_fillFromProto();
  198.     return $this->selectable();
  199.   }
  200.  
  201.   function selectable($cols=2) {
  202.     $t = '';
  203.     #$errorclass = ($this->isValid ? '' : "class='inputerror'");
  204.     $errorclass = '';
  205.     for ($i=0; $i<$this->number; $i++) {
  206.       $t .= "<tr $errorclass><td colspan='$this->colspan'>\n";
  207.       #$t .= "FOO$i";
  208.       $t .= $this->rows[$i]->displayInTable(2);
  209.       $t .= "</td>\n";
  210.       for ($col=0; $col<$cols-2; $col++) {
  211.         $t .= '<td></td>';
  212.       }
  213.       $t .= "</tr>\n";
  214.     }
  215.     return $t;
  216.   }
  217.  
  218.   function selectedValue() {
  219.     return $this->selectable();
  220.   }
  221.  
  222.   function displayInTable($cols=3) {
  223.     //check how many fields we need to have (again) as we might have to show more this time around.
  224.     $this->_fillFromProto();
  225.     //$cols += $this->colspan;
  226.     $t = "<tr><td colspan='$cols'>{$this->description}</td></tr>\n";
  227.     if ($this->editable) {
  228.       $t .= $this->selectable($cols);
  229.     } else {
  230.       //preDump($this);
  231.       //preDump(debug_backtrace());
  232.       $t .= $this->selectedValue();
  233.       $t .= "<input type='hidden' name='{$this->name}' value='".xssqw($this->value)." />";
  234.     }
  235.     return $t;
  236.   }
  237.  
  238.   function update($data) {
  239.     for ($i=0; $i < $this->number; $i++) {
  240.       $rowchanged = $this->rows[$i]->update($data);
  241.       if ($rowchanged) {
  242.         $this->log('JoinData-Row '.$i.' has changed.');
  243.         foreach (array_keys($this->rows[$i]->fields) as $k) {
  244.           #$this->rows[$i]->fields[$this->jtRightIDCol]->changed = $rowchanged;
  245.           #if ($v->name != $this->jtRightIDCol && $v->name != $this->jtLeftIDCol) {
  246.             $this->rows[$i]->fields[$k]->changed = $rowchanged;
  247.           #}
  248.         }
  249.       }
  250.       $this->changed += $rowchanged;
  251.     }
  252.     $this->log('Overall JoinData row changed='.$this->changed);
  253.     return $this->changed;
  254.   }
  255.  
  256.   /**
  257.   *  Count the number of rows in the join table so we know how many to retrieve
  258.   * @return integer number of rows found
  259.   */
  260.   function _countRowsInJoin() {
  261.     $g = quickSQLSelect($this->joinTable, $this->jtLeftIDCol, $this->jtLeftID, $this->fatalsql, 1);
  262.     $this->log('Found '.$g[0].' rows currently in join');
  263.     return $g[0];
  264.   }
  265.  
  266.   /**
  267.   * Trip the complex field within this object to sync()
  268.   * This allows the object to then know our actual value (at last) -- this has to be
  269.   * delayed for as long as possible as an INSERT might be needed before the value of the
  270.   * selection is actually known, but that shouldn't be done until all the data has passed
  271.   * all validation tests
  272.   *
  273.   * @param $name  (unused)
  274.   * @param $force (unused)
  275.   * @return string  sql name=value sequence
  276.   */
  277.   function sqlSetStr($name='', $force=false) {
  278.     //$this->DEBUG=10;
  279.     #echo "JoinData::sqlSetStr";
  280.     $this->_joinSync();
  281.     if (count($this->reportFields) < 1) {
  282.       //We return an empty string as this is only a join table entry,
  283.       //so it has no representation within the row itself.
  284.       return '';
  285.     } else {
  286.       // then we can return the value of the first row (any more doesn't make sense)
  287.       $t = array();
  288.       foreach ($this->reportFields as $f) {
  289.         if (is_array($f)) {
  290.           reset($f);
  291.           $realfield = key($f);
  292.           $aliasfield = current($f);
  293.           $t[] = $this->rows[0]->fields[$realfield]->sqlSetStr($aliasfield);
  294.         } else {
  295.           $t[] = $this->rows[0]->fields[$f]->sqlSetStr();
  296.         }
  297.       }
  298.       return join(', ',$t);
  299.     }
  300.   }
  301.  
  302.   /**
  303.   * synchronise the join table
  304.   */
  305.   function _joinSync() {
  306.     for ($i=0; $i < $this->number; $i++) {
  307.       #echo "before sync row $i oob='".$this->oob_status."' ";
  308.       $this->changed += $this->rows[$i]->changed;
  309.       //preDump($this->rows[$i]->fields[$this->jtRightIDCol]);
  310.       if ($this->rows[$i]->fields[$this->jtRightIDCol]->value !== ''   // damned PHP '' == 0
  311.           && $this->rows[$i]->fields[$this->jtRightIDCol]->value == 0
  312.           && $this->rows[$i]->fields[$this->jtRightIDCol]->changed) {
  313.         //then this row is to be deleted...
  314.         $this->oob_status |= $this->rows[$i]->delete();
  315.       } else {
  316.         $this->log('JoinData::_joinSync(): Syncing row '.$i);
  317. //         preDump($this->rows[$i]);
  318.         $this->oob_status |= $this->rows[$i]->sync();
  319.       }
  320.       $this->oob_errorMessage .= $this->rows[$i]->errorMessage;
  321.       $this->changed += $this->rows[$i]->changed;
  322.       #echo " after sync row $i oob='".$this->oob_status."'";
  323.     }
  324.   }
  325.  
  326.  
  327.   /**
  328.   * Check validity of data
  329.   *
  330.   * override the isValid method of the Field class, using the
  331.   * checkValid method of each member row completed as well as
  332.   * cross checks on other fields.
  333.   * @return boolean data is valid
  334.   */
  335.   function isValid() {
  336.     $this->log('Check JoinData validity: '.$this->name);
  337.     $this->isValid = 1;
  338.     for ($i=0; $i < $this->number; $i++) {
  339.       #echo "val". $this->rows[$i]->fields[$this->jtRightIDCol]->value.";";
  340.       //$this->log('Row: '.$i);
  341.       $this->rows[$i]->isValid = 1;
  342.       if ($this->rows[$i]->fields[$this->jtRightIDCol]->value !== ''   // damned PHP '' == 0
  343.           && $this->rows[$i]->fields[$this->jtRightIDCol]->value == 0
  344.           && $this->rows[$i]->changed) {
  345.         // this row will be deleted to mark it valid in the mean time
  346.         $this->rows[$i]->isValid = 1;
  347.       } elseif ( ($this->rows[$i]->fields[$this->jtRightIDCol]->value == -1
  348.                    || $this->rows[$i]->fields[$this->jtRightIDCol]->value > 0)
  349.                  && $this->rows[$i]->changed) {
  350.         //this row will be sync'd against the database, so check its validity
  351.         //$this->log('Checking valid for row: '.$i);
  352.         $this->isValid = $this->rows[$i]->checkValid() && $this->isValid;
  353.       }
  354.       //echo "JoinData::isValid = '$this->isValid'";
  355.       //echo "JoinData::isValid[$i] = '".$this->rows[$i]->isValid."'";
  356.     }
  357.     //now we need to check the validity of sets of data (e.g. sum of the same
  358.     //field across the different rows.
  359.     foreach ($this->rows[0]->fields as $k => $f) {
  360.       if (isset($this->groupValidTest[$f->name])) {
  361.         $allvals = array();
  362.         for ($i=0; $i < $this->number; $i++) {
  363.           if ($this->rows[$i]->fields[$this->jtRightIDCol]->value > 0) {
  364.             $allvals[] = $this->rows[$i]->fields[$k]->value;
  365.           }
  366.         }
  367.         $fieldvalid = ValidTester($this->groupValidTest[$f->name], $allvals);
  368.         if (! $fieldvalid) {
  369.           for ($i=0; $i < $this->number; $i++) {
  370.             $this->rows[$i]->fields[$k]->isValid = 0;
  371.           }
  372.         }
  373.         $this->isValid = $fieldvalid && $this->isValid;
  374.       }
  375.     }
  376.     //echo "JoinData::isValid = '$this->isValid'";
  377.     return $this->isValid;
  378.   }
  379.  
  380.   /**
  381.   * Change the Id value of each row
  382.   */
  383.   function idChange($newId) {
  384.     for ($i=0; $i < $this->number; $i++) {
  385.       $this->rows[$i]->setId($newId);
  386.     }
  387.   }
  388.  
  389.   /**
  390.   * Set the name base of the rows
  391.   */
  392.   function setNamebase($namebase='') {
  393.     for ($i=0; $i < $this->number; $i++) {
  394.       $this->rows[$i]->setNamebase($namebase);
  395.     }
  396.     $this->protoRow->setNamebase($namebase);
  397.   }
  398.  
  399.   /**
  400.   * set whether each row is editable
  401.   */
  402.   function setEditable($editable=false) {
  403.     for ($i=0; $i < $this->number; $i++) {
  404.       $this->rows[$i]->setEditable($editable);
  405.     }
  406.     $this->protoRow->setEditable($editable);
  407.   }
  408.  
  409. } // class JoinData

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