Class JoinData

Description

an object that manages data related by an SQL JOIN but pretends to be a single form field.

If the element in the table is a selection list then the setup will be as a join table.

We respect the 'field' interface while overriding pretty much all of it.

Primitive class for managing join data. Can be used on its own to just join data or with a selection lists class to make a join table. This may be used to determine the choices that a user is permitted to select (e.g. dropdown list or radio buttons)

Used in a many:many or many:1 relationships (i.e. a field in a table that is the listed in a join table

Typical usage:

  1.    $f new JoinData('jointable''id1'$table1_key'fieldname''label1');
  2.    $f2 new DropList('id2''label2');
  3.    $f2->connectDB('table2'array('id''name'));
  4.    $f2->list->prepend(array('-1','(none)'));
  5.    $f2->setFormat('id''%s'array('name')' (%s)'array('longname'));
  6.    $f->addElement($f2);
  7.    $f3 new TextField('field3''');
  8.    $f->addElement($f3'sum_is_100');
  9.    $f->joinSetup('id2'array('total' => 3));
  10.    $f->use2StepSync 1;

Located in /inc/formslib/joindata.php (line 55)

Field
   |
   --JoinData
Variable Summary
string $colspan
boolean $fatalsql
array $format
string $joinTable
string $jtLeftID
string $jtLeftIDCol
string $jtRightIDCol
integer $number
array $rows
Method Summary
JoinData JoinData ( $joinTable, string $jtLeftIDCol, string $jtLeftID, string $name, [string $description = ''], string $jointable)
void addElement (Field $field, [string $groupValidTest = NULL])
void display ()
void displayInTable ([ $cols = 3])
void idChange ( $newId)
boolean isValid ()
void joinSetup (string $jtRightIDCol, [mixed $format = ''])
void selectable ([ $cols = 2])
void selectedValue ()
void setEditable ([ $editable = false])
void setNamebase ([ $namebase = ''])
string sqlSetStr ([$name $name = ''], [$force $force = false])
void update ( $data)
void _calcMaxNumber ()
integer _countRowsInJoin ()
void _createRow (integer $rowNum)
void _fill ()
void _fillFromProto ()
void _joinSync ()
Variables
string $colspan (line 69)
  • var: number of columns that this field should span in the table
boolean $fatalsql = 0 (line 79)
  • var: SQL errors should be fatal (die())
array $format (line 71)
  • var: formatting control arguments (e.g. maximum number permitted in 1:many)
array $groupValidTest (line 77)
  • var: list of functions that should be applied to the group of results collectively to test validity
string $joinTable (line 57)
  • var: name of the join table (table has columns of form (LeftID, RightID) to join Left and Right tables
string $jtLeftID (line 61)
  • var: value of the left column ID that we are matching
string $jtLeftIDCol (line 59)
  • var: column name in the join table for the column with keys/Ids from the left table
string $jtRightIDCol (line 63)
  • var: column name in the join table for the column with keys/Ids from the right table
integer $number = 0 (line 73)
  • var: number of rows in the join
DBRow $protoRow (line 65)
  • var: prototype DBRow object that is replicated for each entry in the join table (1:many join)
array $reportFields = array() (line 75)
  • var: list of columns to return when the containing object asks for the SQL column=value sequence
array $rows (line 67)
  • var: list of DBRow objects for each row returned in a 1:many join

Inherited Variables

Inherited from Field

Field::$attr
Field::$changed
Field::$DEBUG
Field::$defaultValue
Field::$description
Field::$duplicateName
Field::$editable
Field::$errorclass
Field::$hidden
Field::$isValid
Field::$isValidTest
Field::$longname
Field::$name
Field::$namebase
Field::$notifyIdChange
Field::$oob_errorMessage
Field::$oob_status
Field::$ovalue
Field::$required
Field::$requiredTwoStage
Field::$sqlHidden
Field::$suppressValidation
Field::$useNullValues
Field::$value
Field::$valueCleaner
Methods
Constructor JoinData (line 90)

Create a new joindata object

JoinData JoinData ( $joinTable, string $jtLeftIDCol, string $jtLeftID, string $name, [string $description = ''], string $jointable)
  • string $jointable: see $this->joinTable
  • string $jtLeftIDCol: see $this->jtLeftIDCol
  • string $jtLeftID: see $this->jtLeftID
  • string $name: the name of the field (db name, and html field name
  • string $description: used in the html title or longdesc for the field
  • $joinTable
addElement (line 146)

add a field to the join table

Field will appear in each row returned from the join table

void addElement (Field $field, [string $groupValidTest = NULL])
  • Field $field: the field to be added
  • string $groupValidTest: data validation routine for this field
display (line 195)
void display ()

Redefinition of:
Field::display()
Generic display function
displayInTable (line 222)
void displayInTable ([ $cols = 3])
  • $cols

Redefinition of:
Field::displayInTable()
render this form widget in an html table
idChange (line 383)

Change the Id value of each row

void idChange ( $newId)
  • $newId
isValid (line 335)

Check validity of data

override the isValid method of the Field class, using the checkValid method of each member row completed as well as cross checks on other fields.

  • return: data is valid
boolean isValid ()

Redefinition of:
Field::isValid()
Check the validity of the current data value.
joinSetup (line 114)

Connect the join table and fill from the database

void joinSetup (string $jtRightIDCol, [mixed $format = ''])
  • string $jtRightIDCol: see $this->jtRightIDCol
  • mixed $format: see $this->format (string is converted to array)
selectable (line 201)
void selectable ([ $cols = 2])
  • $cols

Redefinition of:
Field::selectable()
return an html representation of the widget
selectedValue (line 218)
void selectedValue ()

Redefinition of:
Field::selectedValue()
return the current value as text and the widget as a hidden form element
setEditable (line 402)

set whether each row is editable

void setEditable ([ $editable = false])
  • $editable

Redefinition of:
Field::setEditable()
set whether this field is editable or not
setNamebase (line 392)

Set the name base of the rows

void setNamebase ([ $namebase = ''])
  • $namebase

Redefinition of:
Field::setNamebase()
set the namebase for the data storage in the html form
sqlSetStr (line 277)

Trip the complex field within this object to sync()

This allows the object to then know our actual value (at last) -- this has to be delayed for as long as possible as an INSERT might be needed before the value of the selection is actually known, but that shouldn't be done until all the data has passed all validation tests

  • return: sql name=value sequence
string sqlSetStr ([$name $name = ''], [$force $force = false])
  • $name $name: (unused)
  • $force $force: (unused)

Redefinition of:
Field::sqlSetStr()
create an SQL-injection-cleansed string for db statements
update (line 238)
void update ( $data)
  • $data

Redefinition of:
Field::update()
update the value of the object with the user-supplied data in $data
_calcMaxNumber (line 124)

Calculate the maximum number of rows to display (e.g. including spares)

void _calcMaxNumber ()
_countRowsInJoin (line 260)

Count the number of rows in the join table so we know how many to retrieve

  • return: number of rows found
integer _countRowsInJoin ()
_createRow (line 155)

Create a new row from the protorow for storing data

void _createRow (integer $rowNum)
  • integer $rowNum: number of this row (used as unique identifier in the namebase)
_fill (line 169)

Fill from the database

void _fill ()
_fillFromProto (line 176)

Fill from the database one row at a time

void _fillFromProto ()
_joinSync (line 305)

synchronise the join table

void _joinSync ()

Inherited Methods

Inherited From Field

Field::Field()
Field::display()
Field::displayInTable()
Field::getValue()
Field::hidden()
Field::isValid()
Field::log()
Field::selectable()
Field::selectedValue()
Field::set()
Field::setattr()
Field::setEditable()
Field::setNamebase()
Field::sqlSetStr()
Field::text_dump()
Field::update()
Field::__clone()

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