Docs For Class DBLLCField

Description

This implements basic type of lookup combo field.

'Lookup' is a field where the value is chosen from a set of values (like in normal combo field) AND that set of values is got from a query. It is usually used to allow user edit a 1:N (one-too-many) relationship.

The lookup field uses two form fields - one hidden which is named like the field and the other one, read-only text box, which is used to show user textual value.

Lookup fields have also minor inconvenience. If you are displaying the field in the record index, there usually (see below) must be both versions included in the results of the query - both ID and the textual value. ID is named as the field, textual value should have the name of the field and _txt added. (I.e., the field ID would be named 'language', the field text 'language_txt'.) See example below. The detail and edit 'view styles' convert the id=>text at their own.

This quite complicates the query you use to display index ( :-( ), but there are two reasons:

Save database queries. Since the id => text conversion requires a database query, it would require 30 lookups to show a "standard" 30-item index. That is not _really_ heavy load, but it's also not nice.
If you use the DBLJSLCField, you will not be able to filter by the field, since the filter searches the textual version. It would not be possible to search it if it was not present in the query. Hence to be able to filter index by a lookup field, you must have the textual version present in the query. DBLLCField searches by record ID, so it is OK.

If the two difficulties mentioned above do not bother you (you have plenty of processor power), you can set the indexDBConversion property to true. The conversion will then will be done by DB lookup for each index row. You have been warned.

The filter this field implements lets you choose one of the possibile values and show records which have it.

The method of selecting records from a combo is acceptable only for several tenths of records. If you wish to select from more records, you should see the DBLJSLCField class.

Located in /DBLLCField.php (line 57)

DBLField
   |
   --DBLComboField
      |
      --DBLLCField

Variable Summary

bool $checkValueFromPost

string $idDBName

bool $indexDBConversion

string $noneID

string $noneText

DBLQuery $q

string $referenceURL

Method Summary

DBLLCField DBLLCField (string $name, mixed $titleTxt, string $titleHTML, mixed &$q, DBLQuery $query)

void checkValue (mixed $value, mixed &$err, mixed &$r, mixed $new)

void fillChoices ()

void formatDetail (mixed $value, mixed &$r)

void formatEdit (mixed $value, mixed &$r, mixed $dataSource, mixed $formName)

void formatFilter (mixed $value, mixed &$r, mixed $formName)

void formatIndex (mixed $value, mixed &$r)

Variables

bool $checkValueFromPost (line 81)

var: Check that value from the POST (entered in the form) is in the list of allowed values got from a query. This prevents users 'cheating' posts to values they would not be allowed to enter. But requires database lookup and (currently) requires that DBLQuery class implements filtering. It if on (true) by default. May be turned off for performance reasons.

string $idDBName (line 94)

var: Name of the id field used in condition in value check. You may need to set it to 'table.id', if you are joining tables.

bool $indexDBConversion (line 100)

var: Convert vaues from indexes by DB, do not look for them in the $this->name."_txt" row field. This is several times slower, but it let's you create simpler queries. Default is false.

string $noneID (line 69)

var: ID of the 'none' value (default is '0')

string $noneText (line 73)

var: Text of the none value (defaul is localized '<None>')

DBLQuery $q (line 65)

var: Query to get possible values (ids/texts) for this fields. The query must return a row containg (at least) two fields: 'id' which holds record ID and 'text' which holds record text. This usually requires DBLQuery to be able to do some kind of field aliasing.

string $referenceURL (line 89)

var: If set, the field textual value in index and record detail will be a hyperlink pointing to this URL. The field ID will be appended after this URL. So this should be something like "../language/show.php?id=". (This feature is meant to be mostly used to display detail of the record this field "points" to.)

Redefinition of:

DBLField::$referenceURL

Inherited Variables

Inherited from DBLComboField

DBLComboField::$anyID
DBLComboField::$anyText
DBLComboField::$choices

Inherited from DBLField

DBLField::$addAsterixes
DBLField::$allowEmpty
DBLField::$computed
DBLField::$dbName
DBLField::$default
DBLField::$detailAttributes
DBLField::$detailPostfix
DBLField::$detailPrefix
DBLField::$editAttributes
DBLField::$editPostfix
DBLField::$editPrefix
DBLField::$filterAttributes
DBLField::$filterPostfix
DBLField::$filterPrefix
DBLField::$indexAttributes
DBLField::$indexPostfix
DBLField::$indexPrefix
DBLField::$lookupField
DBLField::$name
DBLField::$needsMultipart
DBLField::$noOrderByTitle
DBLField::$readOnly
DBLField::$titleHTML
DBLField::$titleTxt
DBLField::$widgetAttributes

Methods

Constructor DBLLCField (line 110)

Constructor.

DBLLCField DBLLCField (string $name, mixed $titleTxt, string $titleHTML, mixed &$q, DBLQuery $query)

string $name: Field name. See DBLField.
string $titleHTML: Field HTML title. See DBLField.
DBLQuery $query: Query to get values. See query property.

checkValue (line 203)

void checkValue (mixed $value, mixed &$err, mixed &$r, mixed $new)

Redefinition of:

DBLComboField::checkValue()

fillChoices (line 171)

Internal - fill the (inherited) 'choices' array property from database query.

void fillChoices ()

formatDetail (line 149)

void formatDetail (mixed $value, mixed &$r)

Redefinition of:

DBLComboField::formatDetail()

formatEdit (line 186)

void formatEdit (mixed $value, mixed &$r, mixed $dataSource, mixed $formName)

Redefinition of:

DBLComboField::formatEdit()

formatFilter (line 197)

void formatFilter (mixed $value, mixed &$r, mixed $formName)

Redefinition of:

DBLComboField::formatFilter()

formatIndex (line 124)

void formatIndex (mixed $value, mixed &$r)

Redefinition of:

DBLComboField::formatIndex()

Inherited Methods

Inherited From DBLComboField

DBLComboField::DBLComboField()
DBLComboField::acceptFilterValue()
DBLComboField::checkValue()
DBLComboField::formatDetail()
DBLComboField::formatEdit()
DBLComboField::formatFilter()
DBLComboField::formatIndex()
DBLComboField::formatWidget()

Inherited From DBLField

DBLField::DBLField()
DBLField::acceptFilterValue()
DBLField::acceptValue()
DBLField::addCondition()
DBLField::checkValue()
DBLField::formatDetail()
DBLField::formatEdit()
DBLField::formatFilter()
DBLField::formatIndex()
DBLField::jsCheck()
DBLField::setTitle()
DBLField::splitValue()