Docs For Class DBChoiceList

Class DBChoiceList

Description

A choice list based on an SQL statement.

Primitive class on which selection lists can be built from the results of an SQL query. This may be used to determine the choices that a user is permitted to select (e.g. dropdown list or radio buttons) or also to permit additional entries to be created.

Used in a 1:many relationship (i.e. a field in a table that is the primary key in another table)

Note that this class has no real way of displaying itself properly, so it would usually be inherited and the descendent class used.

Typical usage:

$f = new RadioList("myfield", "Field name");
$f->connectDB("mytable", array("id", "name"));
$f->setFormat("id", "%s", array("name"));
$newentryfield = new TextField("name","");
$newentryfield->namebase = "newentry-";
$newentryfield->suppressValidation = 0;
$f->list->append(array("-1","Create new: "), $newentryfield);

Located in /inc/formslib/dbchoicelist.php (line 48)

DBO
   |
   --DBChoiceList

Variable Summary

array $appendedfields

boolean $changed

array $choicelist

tristate $deleted

boolean $distinct

boolean $editable

boolean $extendable

mixed $join

integer $length

string $limit

string $order

array $prependedfields

string $restriction

Method Summary

DBChoiceList DBChoiceList (string $table, [mixed $fields = ''], [string $restriction = ''], [string $order = ''], [string $idfield = 'id'], [string $limit = ''], [mixed $join = ''], [boolean $distinct = false], [boolean $deleted = NULL])

void append (array $values, [Field $field = ''])

void display ()

void fill ()

void prepend (array $values, [Field $field = ''])

mixed selectedValue ([boolean $returnArray = 0])

void set ( $value)

void setDefault (string $val)

code sync ()

void text_dump ()

void update (string $newval, array $data)

array _addedclone (array $a)

void _append ( $fa)

void _mkaddedarray (array $values, [Field $field = ''])

void _prepend ( $fa)

void _reAddExtraFields ()

string _sqlvals ()

void __clone ()

Variables

array $appendedfields (line 72)

var: the list of appended entries

boolean $changed = 0 (line 64)

var: selected value in list has changed

Redefinition of:

DBO::$changed

array $choicelist (line 68)

var: the list of choices available

tristate $deleted (line 66)

var: NULL => do not restrict on deleted column, otherwise WHERE deleted = $deleted

boolean $distinct (line 58)

var: SELECT DISTINCT

boolean $editable = 0 (line 60)

var: list is editable

Redefinition of:

DBO::$editable

boolean $extendable = 0 (line 62)

var: list is extendable by adding new values

mixed $join (line 50)

var: string or array (preferably) that defines the LEFT JOIN

integer $length (line 70)

var: the number of choices available

string $limit (line 56)

var: LIMIT data

string $order (line 54)

var: column for ORDER BY

array $prependedfields (line 74)

var: the list of prepended entries

string $restriction (line 52)

var: an SQL restriction clause to be used in a WHERE

Inherited Variables

Inherited from DBO

DBO::$DEBUG
DBO::$deletable
DBO::$dumpheader
DBO::$errorMessage
DBO::$fatal_sql
DBO::$fields
DBO::$id
DBO::$idfield
DBO::$idfieldreal
DBO::$ignoreId
DBO::$isValid
DBO::$namebase
DBO::$oob_errorMessage
DBO::$oob_status
DBO::$suppressValidation
DBO::$table

Methods

Constructor DBChoiceList (line 98)

Construct the DBlist object.

Construct a new DBList object based on:

database table ($table)
calling for the fields in the array (or scalar) $fields
with an SQL restriction (WHERE clause) $restriction
ordering the listing by $order
using the field $idfield as the control variable in the list (i.e. the value='' in a radio list etc)
with an SQL LIMIT statement of $limit

string $table: the table to be queried for filling
mixed $fields: string for the field or array of field names
string $restriction: an SQL restriction clause to be used in a WHERE
string $order: fields for SQL ORDER clause
string $idfield: the field that should be used as the uniquely identifying value
string $limit: for LIMIT clause
mixed $join: string or array (preferably) that defines the LEFT JOIN
boolean $distinct: return only DISTINCT rows (default: false)
boolean $deleted: deleted=true/false in SQL; NULL means don't restrict

append (line 208)

append a special field (such as "Create new:") to the choicelist

Keep a copy of the field so it can be added again later if necessary, and then use a private function to actually do the adding

void append (array $values, [Field $field = ''])

array $values: list of values to be displayed
Field $field: (optional) a field class object to be placed next to this entry, if possible

display (line 257)

void display ()

Redefinition of:

DBO::display(): Display the object

fill (line 126)

Fill the object from the database using the already initialised members (->table etc).

void fill ()

prepend (line 224)

prepend a special field (such as "Create new:") to the choicelist

Keep a copy of the field so it can be added again later if necessary, and then use a private function to actually do the adding

void prepend (array $values, [Field $field = ''])

array $values: list of values to be displayed
Field $field: (optional) a field class object to be placed next to this entry, if possible

selectedValue (line 390)

determine whih values are selected and return them

return: list of selected values (array) or current value (string)

mixed selectedValue (boolean $returnArray)

boolean $returnArray: return an array of values

set (line 329)

sets the current value of the field

(providing interface to Field object)

void set ( $value)

$value

setDefault (line 408)

set which option in the selection list is the default option

void setDefault (string $val)

string $val: default value to use

sync (line 341)

synchronise with the database

This also creates the true value for this field if it is undefined

return: from statuscodes
global: string $TABLEPREFIX: prefix for SQL table names

code sync ()

text_dump (line 261)

void text_dump ()

Redefinition of:

DBO::text_dump(): Create a quick text representation of the object

update (line 277)

update the value of the list based on user data:

if it is within the range of current values, then take the value
if the field contains a new value (and is allowed to) then keep an illegal value, mark as being changed, and wait until later for the field to be updated
if the field contains a new value (and is not allowed to) or an out-of-range value, then flag as being invalid

void update (string $newval, array $data)

string $newval: the (possibly) new value for the field
array $data: ancillary user data (passed on to any appended or prepended fields)

_addedclone (line 193)

Clone the array field structure

return: clone of $a

array _addedclone (array $a)

array $a: field structure array (see _mkaddedarray())

_append (line 236)

private functions _append and _prepend that will actually add the field

to the field list after it has been properly constructed and saved for future reference

void _append ( $fa)

_mkaddedarray (line 179)

Construct an array suitable for storing the field and the values it takes for later reuse

void _mkaddedarray (array $values, [Field $field = ''])

array $values: list of values to be displayed
Field $field: Field object associated with these values

_prepend (line 240)

void _prepend ( $fa)

_reAddExtraFields (line 248)

add back in the extra fields that were appended/prepended to the

choicelist. Use this if they fields are lost due to a fill()

void _reAddExtraFields ()

_sqlvals (line 369)

Returns an SQL assignment clause

return: of form name='value'

string _sqlvals ()

__clone (line 420)

PHP5 clone method

PHP5 clone statement will perform only a shallow copy of the object. Any subobjects must also be cloned

void __clone ()

Redefinition of:

DBO::__clone(): PHP5 clone method

Inherited Methods

Inherited From DBO

DBO::DBO()
DBO::display()
DBO::log()
DBO::setEditable()
DBO::setNamebase()
DBO::text_dump()
DBO::__clone()

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