Docs For Class DBLBitField

Description

Field of several booleans (checkboxes).

Meant mainly as a means of editting a bit field. But since the choices have their weight (which are bitwise ORed), it may be used to more complicated task than this.

In the edit form/filter, the field is represented by a set of checkboxes, which is presented in a (HTML) table.

In the index/detail, the field is represented by a list of values, which match set bits.

The value of the field may be stored in two ways. First one is a 32-bit integer. If you need to store more bits, DBLBitField can store value as a string. Four lowest bits of each letter are used to store value. To produce real strings, 64 (decimally) is added to each value. For the output to be real string, @ is interchanged with P (@+16). So P means 0, A is 1, B is 2, etc. If you use this storage style, please note that the choice values must also use this convention. This storage style has one disadvantage - you cannot filter by such values since DB engines do not understand it :-( Even when using nubmers, only SQL Queries are supported.

What is "Eliminate subvalues": What is a subvalue? Imagine you have provided following array as values: array(array(1,"Option1"), array(2,"Option2"), array(4,"Option4"), array(7,"All")). Then "options" are subvalues of "all". When "all" is selected, all options and the "all" text would be printed in the record index/detail. Which is not nice. So eliminateSubvalues feature is provided. With it turned on, only "all" will be printed. (Subvalues are detected automatically, which is nice for you, but the complexity of it is n^3 (n is number of values in the values array). So that's why this feature is not turned on by default.

Note on value passing: The weight of the value is stored directly in the form. This prevents problems when possible values are generated from a table and someone changes that table while user is editting the record. This, of course, allow user to submit any value. After the form is submitted the submitted weights are checked if theya are really in the values list. If the small performance penalty concerns you (or you don't want to fill list of values on submit), set the checkWeight property to false. (There is no better way to pass the weight - value descriptions may be same for several weights and I wanted to avoid addidng artifical unique key which would make it more complicated.)

Located in /DBLBitField.php (line 55)

DBLField
   |
   --DBLBitField

Variable Summary

bool $checkWeight

bool $eliminateSubvalues

string $roSeparator

bool $storeAsString

int $tableColumns

array $values

Method Summary

DBLBitField DBLBitField (string $name, string $titleTxt, string $titleHTML, mixed &$values, [bool $storeAsString = false])

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

void addCondition (mixed $value, mixed &$f, mixed &$q)

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)

void formatRO (mixed $value)

string formatTable (string $value)

bool isSubvalue (mixed $value, mixed $subvalue)

string stringOr (int $v1, int $v2)

Variables

bool $checkWeight (line 87)

var: Check if the weight user submitted is really in the list of possible values (weights). This disables cheating in the case you allow only some weight combinations. Defaults to true.

bool $eliminateSubvalues (line 76)

var: Elmininate (do not show) "subvalues" when a value is present. Defaults to false. See class description for details.

string $roSeparator (line 81)

var: Separator of the values in the record index/detail. Defaults to ", ".

bool $storeAsString (line 71)

var: Store value as a string. Filled from constructor. NOTE: When you get values from query, you MUST set this in constructor (since it is used when getting the values).

int $tableColumns (line 65)

var: How many columns will there be in the HTML table. Defaults to 4.

array $values (line 61)

var: Array of possible values. Each element of this array is an two-element array(weight,text). Filled in from constructor.

Inherited Variables

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::$referenceURL
DBLField::$titleHTML
DBLField::$titleTxt
DBLField::$widgetAttributes

Methods

Constructor DBLBitField (line 103)

Constructor.

DBLBitField DBLBitField (string $name, string $titleTxt, string $titleHTML, mixed &$values, [bool $storeAsString = false])

string $name: Name of the field - see DBLField
string $titleTxt: Textual title - see DBLField
string $titleHTML: HTML title - see DBLField
mixed $values: Values (texts) that the user is able to turn on. The parameter can be either an array in the form weight=>text or a DBLDataSource descendant. If it is DBLQuery , the search() method is applied to it and values it returns are stored to the values property. Values must come as the "weight" and "text" column. See also the values property.
bool $storeAsString: Used to fill storeAsString property. Not a required parameter - defaults to false.

acceptValue (line 281)

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

Redefinition of:

DBLField::acceptValue(): Accept value from post.

addCondition (line 322)

void addCondition (mixed $value, mixed &$f, mixed &$q)

Redefinition of:

DBLField::addCondition(): Add condition(s) to the query according to the filter value.

formatDetail (line 204)

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

Redefinition of:

DBLField::formatDetail(): Format field for record detail.

formatEdit (line 243)

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

Redefinition of:

DBLField::formatEdit(): Format field for record edit form.

formatFilter (line 250)

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

Redefinition of:

DBLField::formatFilter(): Format field for the filter form.

formatIndex (line 199)

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

Redefinition of:

DBLField::formatIndex(): Format field for record index.

formatRO (line 157)

Format value read only

Internal function to list contents of the field in textual form.

void formatRO (mixed $value)

mixed $value: Value to display.

formatTable (line 216)

Internal function - format table with choices.

return: HTML formatted table.

string formatTable (string $value)

string $value: Value determining which checkboxes should be turned on.

isSubvalue (line 132)

Check whether value is a subvalue of another value

return: Whether subvalue is really a subvalue of value.

bool isSubvalue (mixed $value, mixed $subvalue)

mixed $value: Value to match
mixed $subvalue: Is tested to be subvalue of value

stringOr (line 262)

Do binary OR on weights expressed as strings.

return: ORed value.

string stringOr (int $v1, int $v2)

int $v1: First value to or
int $v2: Second value to or

Inherited Methods

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()