Docs For Class DBLField

Description

Base field class.

Defines methods and attributes all fields should have (with several exceptions - see attribute description). Derive all fields from it. It also provides implementation of a few methods supposing the field contains text (not because all fields are text, but because most of them are textual and so they can use the default implementation).

Located in /DBLField.php (line 30)

Direct descendents

Class	Description
DBLDateTimeField	Field used to display/edit date and/or time.
DBLTextField	Class to edit a text field.
DBLMemoField	DBLMemoField class is used to edit longer texts - notes, descriptions, etc.
DBLBoolField	Boolean field represented by a checkbox widget.
DBLConditionField	Can be used to add custom (arbitrary) condition(s) to the filter.
DBLComboField	Combo field - selects one of N choices.
DBLBitField	Field of several booleans (checkboxes).
DBLFileField	Field for storing files (and also image files)
DBLJSEditField	Textual field whose contents are edited in external javascript window.
DBLLabelField	This is just a simple class.

Variable Summary

integer $addAsterixes

bool $allowEmpty

bool $computed

string $dbName

mixed $default

string $detailAttributes

string $detailPostfix

string $detailPrefix

string $editAttributes

string $editPostfix

string $editPrefix

string $filterAttributes

string $filterPostfix

string $filterPrefix

string $indexAttributes

string $indexPostfix

string $indexPrefix

mixed $lookupField

string $name

bool $needsMultipart

bool $noOrderByTitle

bool $readOnly

string $referenceURL

string $titleHTML

string $titleTxt

string $widgetAttributes

Method Summary

DBLField DBLField (string $name, string $titleTxt, mixed $titleHTML, string $titmeHTML)

void acceptFilterValue (string $value, array &$r, array &$arr)

array acceptValue (string $value, array &$err, array &$r, bool $new)

void addCondition (string $value, array &$f, DBLQuery &$q)

bool checkValue (string $value, array &$err, array &$r, bool $new)

string formatDetail (string $value, array &$r)

string formatEdit (string $value, array &$r, int $dataSource, string $formName)

string formatFilter (string $value, array &$r, string $formName)

string formatIndex (string $value, array &$r)

string jsCheck (string $formName, bool $new)

void setTitle (string $titleTxt, string $titleHTML)

void splitValue (string $value, string &$op1, string &$val1, string &$op2, string &$val2)

Variables

integer $addAsterixes (line 142)

var: Specifies how (and if) to automatically asterixes to the value entered in the filter form. The asterixes are only added when there are no asterixes/question marks in the value itself. The values are:
- 0: Add no asterixes
- 1: Append asterix after the value
- 2: Prepend asterix before the value
- 3: Prepend/append asterix after and before the value.

bool $allowEmpty (line 122)

var: Allow empty input. The default is true. Has sense only for some fields (It has none for, e.g., boolean field represented by a checkbox).

bool $computed (line 128)

var: Tells DB engine that this field is "computed" in the querry. Currently it is only used by the SQL interface to put the condition(s) containing this field to the HAVING section instead of default WHERE.

string $dbName (line 52)

var: Name of the field in (filtering/setting) database queries. By default, it is the same as $name. You may need to change it, e.g., if you need to specify in which table the field should be (for WHERE statements). Note that this property is NOT used for getting field data. $name is used for that purpose.

mixed $default (line 132)

var: Default value of the field (used when creating new record).

string $detailAttributes (line 88)

var: Attributes to add to a <TD> tag starting cell with this field in the record detail. Must start with a space! You will usually want put things like ' ALIGN="right"' here.

string $detailPostfix (line 96)

var: Postfix to add just before the field's value in the record detail.

string $detailPrefix (line 92)

var: Prefix to add just before the field's value in the record detail.

string $editAttributes (line 74)

var: Attributes to add to a <TD> tag starting cell with this field in the edit form. Must start with a space! You will usually want put things like ' ALIGN="right"' here.

string $editPostfix (line 82)

var: Postfix to add just after the field's value in the edit form.

string $editPrefix (line 78)

var: Prefix to add just before the field's value in the edit form.

string $filterAttributes (line 102)

var: Attributes to add to a <TD> tag starting cell with this field in the filter form. Must start with a space! You will usually want put things like ' ALIGN="right"' here.

string $filterPostfix (line 110)

var: Postfix to add just before the field's value in the filter form.

string $filterPrefix (line 106)

var: Prefix to add just before the field's value in the filter form.

string $indexAttributes (line 60)

var: Attributes to add to a <TD> tag starting cell with this field in the index. Must start with a space! You will usually want put things like ' ALIGN="right"' here.

string $indexPostfix (line 68)

var: Prefix to add just before the field's value in the record index

string $indexPrefix (line 64)

var: Postfix to add just after the field's value in the record index.

mixed $lookupField (line 164)

Specifies this is a lookup field (means DBLView has to sort by dbName_txt instead of dbName).

string $name (line 36)

var: Name of the field. Used to get field data and to reference it in formats. Do not change!

bool $needsMultipart (line 149)

var: This field must be in a multipart form. For internal use. Defaults to false, DBLFileField sets this to true in its constructor. DBLView uses this to determine whether the edit form should have the 'multipart/form-data' encoding.

bool $noOrderByTitle (line 159)

var: Do not show the ordering link in the title of this column (even when enabled in view). Defaults to false.

bool $readOnly (line 56)

var: The field is read only - in form it is shown as a value (not a widget) and it is ignored if you pass it to the DBLViev::applyValues(). (NOTE: Some subclasses may not (yet) implement this.)

string $referenceURL (line 154)

var: URL this field will point to. Currently works only in index. Record ID will be appended after this URL.

Redefined in descendants as:

string $titleHTML (line 44)

var: Title in HTML form.

string $titleTxt (line 40)

var: Title in textual form.

string $widgetAttributes (line 117)

var: Additional attributes of the widget in the edit form. Must start with a space! There is no duplicate check, so check with attributes of the widget DBLIB sets. You can't use this property to override them! Widget attributes must start with a space!

Methods

Constructor DBLField (line 175)

Constructor.

DBLField DBLField (string $name, string $titleTxt, mixed $titleHTML, string $titmeHTML)

string $name: The name of the field. Used to fill the $name property.
string $titleTxt: The title of the field in text. Used to fill the $titleTxt property.
string $titmeHTML: The title of the field in HTML. Used to fill the $titleHTML property. When it is empty, the htmlspecialchars($titleTxt) is used instead.

acceptFilterValue (line 378)

Accept value from the filter.

Take value from the filter and set the corresponding value(s) in the filter array. The filter array will then be passes to the addCondition method below. Please note, that this function may not actually refuse passed value.

void acceptFilterValue (string $value, array &$r, array &$arr)

string $value: Supposed value from post ($r[$field->name]).
array $r: Reference to the $_POST array.
array $arr: (Reference to) array where to store filter data.

Redefined in descendants as:

acceptValue (line 354)

Accept value from post.

Check value from post, do conversions and return which fields in the database should be set and to what.

return:
Returns associative array (name => value). The keys are db field names, the values are values to which set the db field. When an error occured, the function should return an empty array. The function should NOT do DB-specific conversions (like enclosing in apostrophes, doing AddSlashes etc.)!
NOTE: The current implementation allows easy implementation of multi-db-value fields. The downside is, that it does not pass any value-type information to the DB engine. It is no problem now, since SQL does not need this, but it may be in the future...

array acceptValue (string $value, array &$err, array &$r, bool $new)

string $value: Supposed value from post ($r[$field->name]).
array $err: (Reference to) array where to store error messages.
array $r: Reference to the $_POST array.
bool $new: We are creating new record

Redefined in descendants as:

addCondition (line 451)

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

This method 'sets the filter' for this field.

void addCondition (string $value, array &$f, DBLQuery &$q)

string $value: Supposed value from post ($r[$field->name]).
array $f: Reference to the filter array (set by acceptFilter())
DBLQuery $q: Query to affect.

Redefined in descendants as:

checkValue (line 323)

Check value (from post)

Checks whether value that we got from post is valid. If so, the function should return true. If not the function should add (textual, no HTML!) error message(s) to the $err array and return false.

This functionality is not contained directly in the acceptValue() method to allow (check value) code reuse by subclasses.

return: True if value is OK, false if an error occured (and line(s) is/are added to $err array)

bool checkValue (string $value, array &$err, array &$r, bool $new)

string $value: Value from post.
array $err: Array where to store error messages
array $r: Array with post values
bool $new: We are creating new record

Redefined in descendants as:

DBLDateTimeField::checkValue() : Check value method is not implemented in this class, since checking value is tightly integrated with parsing the value in acceptValue().
DBLPasswordField::checkValue()
DBLNumberField::checkValue()
DBLComboField::checkValue()
DBLLCField::checkValue()
DBLJSLCField::checkValue()

formatDetail (line 248)

Format field for record detail.

return:
HTML formatted field value.

string formatDetail (string $value, array &$r)

string $value: value (Supposed) field value ($r[$field->name]).
array &$r: r Record we format (array of name=>value).

Redefined in descendants as:

formatEdit (line 267)

Format field for record edit form.

return: HTML formatted field value.

string formatEdit (string $value, array &$r, int $dataSource, string $formName)

string $value: (Supposed) field value ($r[$field->name]).
array $r: Data of the record we format (array of name=>value). What it points to depends on dataSource, see below.
int $dataSource
: Data source to use. It may be one of the DBL_DS_* constants:
- DBL_DS_DB: Means the record is from database and $r points to it.
- DBL_DS_NEW: We are creating new record. Field should ignore $value * and $r and get the value from its defaults.
- DBL_DS_POST: We are re-editing record (there were errors upon post). $r points to the $_POST field.
string $formName: Name of the form in which the field is (useful for JavaScript).

Redefined in descendants as:

formatFilter (line 280)

Format field for the filter form.

return: HTML formatted field value.

string formatFilter (string $value, array &$r, string $formName)

string $value: (Supposed) field value ($r[$field->name]).
array $r: Record we format (array of name=>value).
string $formName: Name of the form in which the field is (useful for JavaScript).

Redefined in descendants as:

formatIndex (line 234)

Format field for record index.

return: HTML formatted field value.

string formatIndex (string $value, array &$r)

string $value: (Supposed) field value ($r[$field->name]).
array $r: Record we format (array of name=>value).

Redefined in descendants as:

jsCheck (line 295)

Create javascript to check the field value before post.

The javascript code should check field value, display an error when something is wrong and return(false) (to prevent submitting the form).

return: The javascript code to check the field.

string jsCheck (string $formName, bool $new)

string $formName: The name of the form the field is in.
bool $new: We will create new record (false = we are editing old record).

Redefined in descendants as:

setTitle (line 220)

Set title of the field.

Sets $titleTxt and $titleHTML properties from the arguments of the method. The only real use is that it automatically uses htmlspecialchars($titleTxt) when $titleHTML is empty.

void setTitle (string $titleTxt, string $titleHTML)

string $titleTxt: Textual representation of the title.
string $titleHTML: HTML representation of the title.

splitValue (line 420)

Utility function - split value to the operator(s) and value(s).

DBLIB supports filtering by conditions (less than, greater, ...). Even by two conditions in one value (>=5<=10). This is a utility function which parses such filter values to operators and values.

op1 will be set to first operator, or to: - = When no operator is used and * value does not contain asterix or question mark. - wild When no operator is used and value contains asterix or question mark.

val1 will be set to the first value. op2 will be set to the second operator (or to an empty string when none are present). val2 will be set to the econd value (or to an empty string when none are present.)

void splitValue (string $value, string &$op1, string &$val1, string &$op2, string &$val2)

string $value: Value to parse.
string $op1: Reference to first operator.
string $val1: Reference to first value.
string $op2: Reference to second operator.
string $val2: Reference to second value.