Class DBLView

Description

DBLView is THE base class of DBLIB.

It allows you to print filter forms, record indexes, record details, edit records. And so on. (These functions that you are supposed to use most of the time have 'Important!' in their description.) It uses (almost) all other classes for these purposes. DBLQuery for communicating with the database, DBLField for printing and editing fields.

There is currently only one DBLView class, but you are free to modify some of its methods to gain different look of the output or to include other features. The method structure is made with the easy customization in mind.

ROFF NOTE: DBLView uses the roff parameter to pass record offset - offset of the first record in the record index (paging).

URL PROPERTIES NOTE: The 'URL' fields contain URLs. But they have some rules, because the URLs get a bit modified (or better - parameters are appended to them). So:

  • newURL, submitURL and filterURL are not modified, they must be complete URLs.
  • indexURL must end either with '?' ('edit.php?') or by '&' ('edit.php?myparam=val&')
  • editURL, detailURL and deleteURL must end with a '='. After that, a record id will be appended. So valid value is, for example, 'detail.php?id=', which will become something like 'detail.php?id='
See examples to clarify this, it is actually simple and logical :-)

FORMATS NOTE: DBLView uses formats to describe the layout of record index/detail/form table. They have common format. The rows in the format are separated by LF's (\n), the field names by semicolons (';'). Field name can be either a name, or a number,name. When the number is present, it designates how many columns the field will span. The columns are counted in 'field' columns, not the 'table' columns. I will explain it. Let's have following format: "name;author\n2,description". It is complete, because description will span two 'fields'. The actual table layout will be:

| nameLabel | nameValue | authorLabel | authorValue |
| descLabel | descValue                             | 
As you may see, the descValue actually spans three table columns. But you don't have to bother with this, you just tell it to span 2 fields and DBLView will take care of the rest.

Up to now it was quite simple :-) The system gets a bit more complicated with the possibility of having several fields in one table cell. When field names are separated by colons (':'), they are printed in one cell. The column count can be present only before the first field (of course). Only the label of the first field is printed (labels/titles of the following fields are just ignored).

Example: Let's have definition "name;author\n2,printedOutMonth;printedOutYear". This will be presented as:

| nameLabel    | nameValue | authorLabel | authorValue |
| poMonthLabel | poMonthValue poYearValue              | 
The label for the month has to be in sync with this, so it will be something like 'Printed out' ignoring the fact the field contains month. You will also have to set poYearValue detail prefix to something like '&nsbp;/ ' to separate the values correctly.

Formal definition:

FORMAT := ROW
ROW := ROW '\n' ROW
ROW := FIELD
FIELD := FIELD ';' FIELD
FIELD := FIELDNAMES
FIELD := SPAN ',' FIELDNAMES
FIELDNAMES := FIELDNAME
FIELDNAMES := FIELDNAME ':' FIELDNAMES
FIELDNAME := Name of the field, a string.
SPAN := Integer number greater than 1

ORDER DEFINITION NOTE: Order definition is an asociative array. When the key is numerical, the value is supposed to be the name of the field, by which to order. Field's dbName is then used to setup the order and titleTxt is used as the name of the choice.

When the key is textual, it is supposed to be the name fo the choice. The value is then order definition, which is passed directly to DBLQuery::setOrder().

You wonder why numerical? Well, PHP assigns numerical indexes automatically, if you don't specify a key. For example:

$orderDef = array("year", "Name" => "lastName, firstName");
Will create order with two choices. First order will be by the year field, using its titleTxt and dbName, the second will be named "Name" and when selected, the order set will be "lastName, firstName". You can use this to specify arbitrary orders (like in this example).

Located in /DBLView.php (line 102)


	
			
Variable Summary
Method Summary
DBLView DBLView (string $filterName, [array $rights = false])
void addField (DBLField &$field)
void addHiddenField (string $name, string $value)
string applyButton ()
void applyFilter (DBLQuery &$q, string $format, array &$orderDef, string $defaultOrder)
void applyFilterValues (string $format)
integer applyValues (DBLQuery &$q, string $format, bool $new, string &$newID, string $errorHeaderFile, [array $err = array()])
string clearButton ()
void detail (DBLQuery &$q, string $format, string $rid)
string detailAutoReferences (string $rid)
string detailFooter (int $cols)
string detailHeader (int $cols)
string detailRowEnd (int $cols)
string detailRowStart (int $cols)
void edit (DBLQuery &$q, string $format, int $dataSource, string $rid, bool $new)
string editAutoReferences (string $rid, int $dataSource, bool $new)
string editFooter (int $cols, int $dataSource)
string editHeader (int $cols, int $dataSource)
string editRowEnd (int $cols, int $dataSource)
string editRowStart (int $cols, int $dataSource)
string fieldDetail (array &$names, int $colCnt, array $r)
string fieldEdit (array &$names, int $colCnt, array $r, int $dataSource, string &$js, mixed $val)
string fieldFilter (array &$names, int $colCnt, array $r, DBLQuery &$q, array &$orderDef)
string fieldIndex (string $f, array &$r, int $cols)
void filter (DBLQuery &$q, string $format, array &$orderDef, string $defaultOrder)
string filterFooter (int $cols)
string filterHeader (int $cols)
string filterRowEnd (int $cols)
string filterRowStart (int $cols)
string formatIndexRecord (string &$fa, array &$r)
void index (DBLQuery &$q, string $format, [int $roff = -1])
string indexAutoReferences (int $roff, bool $moreRecords)
void indexColumnTitle (string $name)
string indexFooter (string &$fa, int $cols)
string indexHeader (string &$fa, int $cols)
string indexRecordEnd (array &$r)
string indexRecordStart (array &$r)
string indexRowEnd (array &$r)
string indexRowStart (array &$r)
void orderCombo (array &$orderDef, int $style)
void parseField (string $fieldDesc, int &$cols, array &$names, bool $convertCols)
void parseFormat (string $format, array &$fArr, int &$cols, bool $includeLabels)
void printErrorMessage (array $err, string $errorHeaderFile)
void printPageHeader (string $headerFile)
void printRecord (DBLQuery &$q, string &$format, bool $ro, int $dataSource, string $rid, bool $new)
void setQueryOrder (mixed &$q, mixed &$orderDef, mixed $defaultOrder)
void standardEdit (DBLQuery &$q, string $format, string $header, string $applyFormat, [array $err = array()])
string submitButton (int $cols, int $dataSource)
string tableStart (int $style)
void unauthorized (string $fromWhere)
Variables
string $applyAttributes (line 272)
  • var: Attributes of the TD tag before the "Apply" field (in the filter)
bool $autoReferences (line 207)
  • var: Generate automatic back/forward/new record/delete/index/... references. Defaults to true. Turn off if you wish to have the references done other way :-)
string $clearAttributes (line 276)
  • var: Attributes of the TD tag before the "Clear" field (in the filter)
string $deleteField (line 139)
  • var: Name of the field to use as a 'delete' link. The deleteURL property determines where is the delete script. See URL properties note in class description.
bool $deleteJSConfirm (line 196)
  • var: Whether to require confirmation (by javascript popup dialog) when deleting record. Defaults to true.
string $deleteURL (line 181)
  • var: URL of the record delete script. Used to delete a record. See URL properties notes in class description. 'delete.php?id=' by default.
string $detailField (line 133)
  • var: Name of the field to use as a 'detail' link. The detailURL property determines where is the detail script. See URL properties note in class description.
string $detailURL (line 176)
  • var: URL of the record detail script. Used for displaying a record detail. See URL properties notes in class description. 'detail.php?id=' by default.
string $editField (line 127)
  • var: Name of the field to use as a 'edit' link. The editURL property determines where is the edit script. See URL properties note in class description.
string $editRecordButton (line 258)
  • var: Text on the edit record button (in the form). By default it is localized (gettext) 'Change record'.
string $editRecordLink (line 263)
  • var: Text of the edit record link. By default it is localized (gettext) 'Edit'.
string $editRecordTitle (line 243)
  • var: Title of the edit record HTML table. By default it is localized (gettext) 'Edit record'.
string $editURL (line 170)
  • var: URL of the record edit script. Used for displaying a form used to edit record. See URL properties notes in class description. 'edit.php?id=' by default.
array $fields (line 110)
  • var: Fields which are defined in the view. You should use this field as read-only when you need to gain access to one of the set fields (e.g., to change its properties). To add fields to this array, please use the addField() method.
array $filter (line 218)
  • var: Internal - keeps set filter values. It is populated from session variable.
string $filterName (line 223)
  • var: (Internal) The name of the filter. Populated from the constructor parameter.
string $filterTitle (line 248)
  • var: Title of the filter HTML table. By default it is localized (gettext) 'Filter'.
string $filterURL (line 191)
  • var: URL where to post the filter form. Noting is appended after it (since the form method is post). 'filter.php' by default.
string $formName (line 121)
  • var: Form name to use for edit and filter form. Default is 'editFrm'. You need to change this when you have more forms on a page (so javascript can address fields in proper form).
array $hiddenFields (line 201)
  • var: Array of hidden values to be included in the edit form (as hidden inputs). Do not access directly, add by addHidden() method.
string $idFieldName (line 292)
  • var: Name of the field to be used as primary query key in the standardEdit. Defaults to "id".
string $indexURL (line 164)
  • var: URL of the record index. Used in redirection after edit and in auto references. Roff parameter is automatically appended after it. 'index.php?' by default.
bool $multipart (line 213)
  • var: If the form type should be 'multipart/form-data'. This type is required for forms which contain file uploads. Defaults to false. (NOTE: This COULD be set automatically, maybe in some following version...)
string $newRecordButton (line 253)
  • var: Text on the new record button (in the form). By default it is localized (gettext) 'New record'.
string $newRecordLink (line 238)
  • var: Text of the new record link. By default it is localized (gettext) 'New record'.
string $newRecordTitle (line 233)
  • var: Title of the new record HTML table. By default it is localized (gettext) 'New record'.
string $newURL (line 158)
  • var: URL of the 'New record' link. This is the exception from URLS - this URL is not modified. 'edit.php?id=0' by default.
string $orderAttributes (line 280)
  • var: Attributes of the TD tag before the "Order" field (in the filter)
int $pageLength (line 115)
  • var: Length of the index record page. Default is 30 records per page. If you set this to 0, all records will be displayed on one page.
string $recordDetailTitle (line 268)
  • var: Text above the record detail. By default localized (gettext) "Record detail".
int $recordNo (line 153)
  • var: Internal record number (from from the top of the index). Used only in index, the index() method increments it. It may be used by your routines for various purposes.
array $rights (line 228)
  • var: The rights user has. You may need to modify them to tweak DBLView behaviour sometimes. Populated from the constructor parameter.
int $rowNo (line 147)
  • var: Internal count of rows in the table. It is meant to be user for row coloring (even rows with one background color, odd with another). Row starting function is responsible to maintain this variable, so if you override it, you should increment it yourself. It is set to before a table is started automatically.
int $sortByColumnTitles (line 298)
  • var: Show column titles as links to sort by that column. - Do not make links, 1 - sort ascending on first click, -1 - sort descending on first click. Defaults to 1.
string $submitURL (line 186)
  • var: URL where to post the record edit form. Noting is appended after it (since the form method is post). 'edit.php' by default.
string $userJSCheck (line 287)
  • var: User-defined javascript to check the validity of the data in the edit form. Executed after all other checks. The javascript should check what it needs, when it discovers an error, it should display an error message (alert()) and return false. Defaults to empty string (no code).
Methods
Constructor DBLView (line 309)

Constructor.

DBLView DBLView (string $filterName, [array $rights = false])
  • string $filterName: Name of the filter. Should be unique for each view in your application.
  • array $rights: Rights the user has. See DBLAuth::getRights() for the right array decription. When the parameter is missing, user is assumed to have all rights.
addField (line 373)

Add field to the view

Adds field to the view. Beware! The reference to the field is stored, the field is not copied (for performance reasons). So if you do:

$f =& new DBLTextField("name1",...); $view->addField($f); $f->allowEmpty = false;

It will work OK. But if you, after this code, do:

$f =& new DBLTextField("name2,...); $view->addField($f);

You will end up with 'two fields2'. This is because references are not pointers (see PHP language manual for deeper explanation). You have to unset() variable, if you wish to assign new field to it.

void addField (DBLField &$field)
addHiddenField (line 390)

Adds hidden field

Adds new hidden value (hidden type field) to the view. All hidden fields will be placed in the edit form.

void addHiddenField (string $name, string $value)
  • string $name: Name of the field
  • string $value: Value of the field
applyButton (line 1082)

Formats apply button of the fliter form.

It is here for you to override if you wish to have different button.

  • return: HTML of the button.
string applyButton ()
applyFilter (line 1732)

Apply filter to the query. Not-so important!

Adds conditions by an active filter. Call this only when you don't call filter()! You may actually need this method in two cases:

  • When there is no filter form in the page
  • When the filter form is below the index record

void applyFilter (DBLQuery &$q, string $format, array &$orderDef, string $defaultOrder)
  • DBLQuery &$q: Query to affect.
  • string $format: Fields which should be in the filter. You will usually want to use the format of the filter form. See FORMATS NOTE for more information.
  • array &$orderDef: Order definition. See ORDER DEFINITION NOTE in the class description for more information.
  • string $defaultOrder: Default order to be passed to DBLQuery::setOrder when no order is set in the filter. When empty, order is not set.
applyFilterValues (line 1844)

Processes filter POST (or GET).

This function processes a POST from the filter form. It let's fields parse values and stores what the fields return.

When script was called by the GET method, it gets the data from the _GET array instead of _POST. This lets you create links which will setup filters! Set the _clear parameter if you wish to clear the filter.

For example, you may create link like:

Show * Johns
(Supposing filter.php calls applyFilterValues() and then redirects to record index.

void applyFilterValues (string $format)
  • string $format: Format of the filter - used to determine which fields were contained in the filter.
applyValues (line 1607)

Process post from the edit form - apply values to the database. Important!

This function takes value posted by the edit form and tries to apply them into the database. It may happen, that some field(s) refuse the value. In that case, the function prints out an error message to the user.

You are supposed to redirect user to the record index when the values are accepted. In the other case, you should call the edit() method with the data source set to DBL_FS_POST to let user correct the errors.

  • return: -1 on error, 0 on OK.
integer applyValues (DBLQuery &$q, string $format, bool $new, string &$newID, string $errorHeaderFile, [array $err = array()])
  • DBLQuery $q: Query to use to apply records. When you are editing an old record, it should have set conditions so that only the record the user was editing is affected.
  • string $format: Only the fields listed in this format will be affected. See FORMATS NOTE in the class description on the format details. (It seems not logical at first, to have here format - this function does not need formatting information. In older versions you passed an array of field names. But it proved inconvenient, since when you have added field, you have to add it to both edit format and the list of accepted fields. So this solution was chosen where you can in the most cases just pass edit format here and all will be fine.)
  • bool $new: A new record will be created when this is set. Old record will be modified otherwise (determined by query conditions).
  • string &$newID: Reference to a variable where the id of the new record will be put, when a new record was created. May not be supported by all DBLQuery classes. See DBLQuery::addRecord() for discussion on this.
  • string $errorHeaderFile: File to include before an error message. See printErrorMessgae() method.
  • array $err: Errors from user check. Array of string. Each string is considered an error message (like those produced by fields). Can be used to nicely and simply show your own error messages.
clearButton (line 1095)

Formats clear/reset button of the fliter form.

It is here for you to override if you wish to have different button.

  • return: HTML of the button.
string clearButton ()
detail (line 1530)

Print out record detail.

Important!

void detail (DBLQuery &$q, string $format, string $rid)
  • DBLQuery $q: Query to get record data. It must have set conditions so that the first record returned by search() and then nextRecord() will be the one to show/edit.
  • string $format: Table format. See FORMATS NOTE in the class description.
  • string $rid: Record ID. Will not be used directly, just put to links.
detailAutoReferences (line 1339)

Format detail auto references.

It is here for you to override.

  • return: HTML of the auto references
string detailAutoReferences (string $rid)
  • string $rid: ID of the current record.
detailFooter (line 915)

Return detail table footer.

This method should format and return the footer row(s) of the record detail table. It is here for you to override if you wish to have different-looking header.

  • return: Formatted HTML footer row.
string detailFooter (int $cols)
  • int $cols: Number of columns the table has.
detailHeader (line 835)

Return detail table header.

This method should format and return the header row(s) of the record detail table. It is here for you to override if you wish to have different-looking header.

  • return: Formatted HTML header row.
string detailHeader (int $cols)
  • int $cols: Number of columns the table has.
detailRowEnd (line 885)

Return how to end record detail table row.

It is here for you to override.

  • return: HTML of the row end.
string detailRowEnd (int $cols)
  • int $cols: Number of columns the table has.
detailRowStart (line 855)

Return how to start record detail table row.

It is here for you to override.

  • return: HTML of the row start.
string detailRowStart (int $cols)
  • int $cols: Number of columns the table has.
edit (line 1503)

Print out edit form.

Important!

void edit (DBLQuery &$q, string $format, int $dataSource, string $rid, bool $new)
  • DBLQuery $q: Query to get record data. It must have set conditions so that the first record returned by search() and then nextRecord() will be the one to show/edit.
  • string $format: Table format. See FORMATS NOTE in the class description.
  • int $dataSource: Source of the data, one of the DBL_FS_* constants.
  • string $rid: Record ID. Will not be used directly, just put to links.
  • bool $new: Tells whether we are editing new record or an old one. It should be on when dataSource is DBL_DS_NEW, it actually duplicates it in these cases. It is here for the case when we re-display data we got from POST, because there was an error.
editAutoReferences (line 1367)

Format edit auto references.

It is here for you to override.

  • return: HTML of the auto references
string editAutoReferences (string $rid, int $dataSource, bool $new)
  • string $rid: ID of the current record.
  • int $dataSource: Source of the record to edit. One of the DBL_FS_* constants.
  • bool $new: Whether we are creating new record. (Otherwise we are editing an old one.)
editFooter (line 932)

Return edit form table footer.

This method should format and return the footer row(s) of the edit form table. It is here for you to override if you wish to have different-looking header.

  • return: Formatted HTML footer row.
string editFooter (int $cols, int $dataSource)
  • int $cols: Number of columns the table has.
  • int $dataSource: Source of the record to edit. One of the DBL_FS_* constants.
editHeader (line 811)

Return edit form table header.

This method should format and return the header row(s) of the edit form table. It is here for you to override if you wish to have different-looking header.

  • return: Formatted HTML header row.
string editHeader (int $cols, int $dataSource)
  • int $cols: Number of columns the table has.
  • int $dataSource: Source of the record to edit. One of the DBL_FS_* constants.
editRowEnd (line 900)

Return how to end edit record form table row.

It is here for you to override.

  • return: HTML of the row end.
string editRowEnd (int $cols, int $dataSource)
  • int $cols: Number of columns the table has.
  • int $dataSource: Source of the record to edit. One of the DBL_FS_* constants.
editRowStart (line 871)

Return how to start edit form table row.

It is here for you to override.

  • return: HTML of the row start.
string editRowStart (int $cols, int $dataSource)
  • int $cols: Number of columns the table has.
  • int $dataSource: Source of the record to edit. One of the DBL_FS_* constants.
fieldDetail (line 1180)

Formats field to be shown in the record detail.

You may want to override this if you want "special effects" in the detail.

  • return: Formatted HTML (including TD tags).
string fieldDetail (array &$names, int $colCnt, array $r)
  • array $names: Name(s) of the field to print
  • int $colCnt: The number of table columns the field should occupy.
  • array $r: Current database record. Associative array name=>value.
fieldEdit (line 1222)

Formats field to be shown in the edit form.

You may want to override this if you want "special effects" in the form.

  • return: Formatted HTML (including TD tags).
string fieldEdit (array &$names, int $colCnt, array $r, int $dataSource, string &$js, mixed $val)
  • array $names: Name(s) of the field to print
  • int $colCnt: The number of table columns the field should occupy.
  • mixed $val: Supposed field value ($r[$field->name]).
  • array $r: Current database record. Associative array name=>value.
  • int $dataSource: Source of the record to edit.
  • string $js: Reference to variable to which javascript form checking code should be added.
fieldFilter (line 1264)

Formats field to be shown in the filter form.

You may want to override this if you want "special effects" in the form.

  • return: Formatted HTML (including TD tags).
string fieldFilter (array &$names, int $colCnt, array $r, DBLQuery &$q, array &$orderDef)
  • array $names: Name(s) of the field to print
  • int $colCnt: The number of table columns the field should occupy.
  • array $r: Current database record. Associative array name=>value.
  • DBLQuery $q: Query to which add conditions
  • array $orderDef: Order definition (as passed by user);
fieldIndex (line 621)

Formats field to be shown in the index

You may want to override this if you want "special effects" in the index.

  • return: Formatted HTML (including TD tags).
string fieldIndex (string $f, array &$r, int $cols)
  • string $f: Name of the field to format.
  • array $r: Current database record. Associative array name=>value.
  • int $cols: Number of columns the field should have.
filter (line 1769)

Print out filter form and apply filter to the query.

void filter (DBLQuery &$q, string $format, array &$orderDef, string $defaultOrder)
  • DBLQuery &$q: Query to affect.
  • string $format: Fields which should be in the filter. You will usually want to use the format of the filter form. See FORMATS NOTE for more information.
  • array &$orderDef: Order definition. See ORDER DEFINITION NOTE in the class description for more information.
  • string $defaultOrder: Default order to be passed to DBLQuery::setOrder when no order is set in the filter. When empty, order is not set.
filterFooter (line 947)

Return filter table footer.

This method should format and return the footer row(s) of the filter form table. It is here for you to override if you wish to have different-looking header.

  • return: Formatted HTML header row.
string filterFooter (int $cols)
  • int $cols: Number of columns the table has.
filterHeader (line 962)

Return filter table header

This method should format and return the header row(s) of the filter form table. It is here for you to override if you wish to have different-looking header.

  • return: Formatted HTML header row.
string filterHeader (int $cols)
  • int $cols: Number of columns the table has.
filterRowEnd (line 996)

Return how to end filter form table row.

It is here for you to override.

  • return: HTML of the row end.
string filterRowEnd (int $cols)
  • int $cols: Number of columns the table has.
filterRowStart (line 982)

Return how to start filter form table row.

It is here for you to override.

  • return: HTML of the row start.
string filterRowStart (int $cols)
  • int $cols: Number of columns the table has.
formatIndexRecord (line 670)

Formats index record.

You may want to override this if you want "special effects" in the index.

  • return: Formatted HTML (including row tags).
string formatIndexRecord (string &$fa, array &$r)
  • string $fa: Two dimensional array - parsed format. (Parsed by the parseFormat method - see its description.)
  • array $r: Current database record. Associative array name=>value.
index (line 710)

Show record index.

Important!

This method prints out HTML for the record index.

void index (DBLQuery &$q, string $format, [int $roff = -1])
  • DBLQuery $q: Query to use to get the record data. It should have a filter applied, if it is applicable. (See filter() and applyFilter() methods on how to do this.)
  • string $format: Index format. See format note in class description on the format od the string.
  • int $roff: From which record start printing. Record offset may be also gathered from other sources - the priority list (highest first) is:
    • Third parameter to the index() function
    • "roff" GET parametr
    • DBL_ROFF_<filterName> session variable
    • 0 (when roff is not specified, it will be 0)
indexAutoReferences (line 575)

Format index auto references.

It is here for you to override.

  • return: HTML of the index auto references
string indexAutoReferences (int $roff, bool $moreRecords)
  • int $roff: Record offset of current page.
  • bool $moreRecords: Whether there are ore records or not.
indexColumnTitle (line 408)

Return index column title.

Internal function

void indexColumnTitle (string $name)
  • string $name: Name of the field to print
indexFooter (line 473)

Return index footer

This method should format and return the footer row(s) of the index record table. It is here for you to override if you wish to have different-looking footer. NOTE: The default footer is empty - there's no footer :-)

  • return: Formatted HTML footer row.
string indexFooter (string &$fa, int $cols)
  • string $fa: Two dimensional array - parsed format. (Parsed by the parseFormat method - see its description.)
  • int $cols: Number of columns the table has.
indexHeader (line 445)

Return index header

This method should format and return the header row(s) of the index record table. It is here for you to override if you wish to have different-looking header.

  • return: Formatted HTML header row.
string indexHeader (string &$fa, int $cols)
  • string $fa: Two dimensional array - parsed format. (Parsed by the parseFormat method - see its description.)
  • int $cols: Number of columns the table has.
indexRecordEnd (line 561)

Return how to end index table record.

It is here for you to override. (Default implementation returns row end.)

  • return: HTML of the record end.
string indexRecordEnd (array &$r)
  • array $r: Current record - associative array (associative name=>value)
indexRecordStart (line 533)

Return how to start index table record.

NOTE ON RECORD/ROW: When the first row of the index record is to be started, indexRecordStart() is called. For the following rows (if there are any), indexRowStart() is called. Similarly, when the last row of the index record is to be ended, indexRecordEnd() is called. For the previous row ends (if there are any), indexRowEnd() is called. So for the usual one-row index record format, only indexRecordStart() and indexRecordEnd() are called directly.

It is here for you to override. (Default implementation returns row start.)

  • return: HTML of the record start.
string indexRecordStart (array &$r)
  • array $r: Current record - associative array (associative name=>value)
indexRowEnd (line 547)

Return how to end index table row.

It is here for you to override.

  • return: HTML of the row end.
string indexRowEnd (array &$r)
  • array $r: Current record - associative array (associative name=>value)
indexRowStart (line 509)

Return how to start index table row.

It is here for you to override.

  • return: HTML of the row start.
string indexRowStart (array &$r)
  • array $r: Current record - associative array (associative name=>value)
orderCombo (line 1035)

Formats order combo (and the 'reverse' checkbox too).

Override this if you wish to have different combo/checkbox.

void orderCombo (array &$orderDef, int $style)
  • array $orderDef: Order definition array. See Order definition note in class description for details.
  • int $style: Style of the combo
parseField (line 1118)

Internal function to parse field definition.

This function parses field definition. It: - separates number of columns (if present) - parses name(s) (separated by colon) The number of columns may be converted to the real number of columns the field will occupy (excluding eventual labels).

void parseField (string $fieldDesc, int &$cols, array &$names, bool $convertCols)
  • string $fieldDesc: Field description [cols,]name
  • int &$cols: Reference to the variable where column count will be stored.
  • array &$names: Reference to the variable where field names will be stored (array of strings).
  • bool $convertCols: Whether to convert columns as if the field was in the table with labels (edit/filter tables). If you are calling this when printing record index, it should be off, otherwise on.
parseFormat (line 1152)

Parse textual format to a two-dimensional array.

Parses textual format (see FORMATS NOTE) to a two-dimensional array by rows and columns as specified. Also counts the (maximum) number of columns the table will have.

void parseFormat (string $format, array &$fArr, int &$cols, bool $includeLabels)
  • string $format: Textual format specification.
  • array &$fArr: Reference to the variable where the result array will be stored.
  • int &$cols: Reference to the variable where the column count will be stored.
  • bool $includeLabels: Include also a 1-cell label for each field in the column count. Turn this off for index, otherwise keep it on.
printErrorMessage (line 1564)

Prints out error message (after a POST error).

void printErrorMessage (array $err, string $errorHeaderFile)
  • array $err: Array of strings, each element is an error message.
  • string $errorHeaderFile: Name of the file to include before the message (usually HTML page headers.)
printPageHeader (line 1552)

Prints out page header (before edit form / error message).

By default just includes given file. This method is called by the standardEdit()/applyValues()/printErrorMessage() methods with the file given to them. Override this, if you need to provide different page header. (Alternatively, you can put the code into the header file, but overriding a method is sometimes cleaner.)

void printPageHeader (string $headerFile)
  • string $headerFile: @headerFile Name of the file to include.
printRecord (line 1404)

Print record detail/edit form table.

This function prints the record table, either as record detail or as a record edit form. These two share a common algorithm, however, with the deatures added, there are too many exceptions and conditions, so I consider split this method to two. You are not supposed to overrid it anyway (it is quite complicated).

void printRecord (DBLQuery &$q, string &$format, bool $ro, int $dataSource, string $rid, bool $new)
  • DBLQuery $q: Query to get record data. It must have set conditions so that the first record returned by search() and then nextRecord() will be the one to show/edit.
  • string $format: Table format. See FORMATS NOTE in the class description.
  • bool $ro: True - print record detail, false - print tedord edit form.
  • int $dataSource:
    • Source of the data, one of the DBL_FS_* constants.
  • string $rid: Record ID. Will not be used directly, just put to links.
  • bool $new: Tells whether we are editing new record or an old one (has no sense when ro is true). It should be on when dataSource is DBL_DS_NEW, it actually duplicates it in these cases. It is here for the case when we re-display data we got from POST, because there was an error.
resetHiddenFields (line 398)

Reset the hidden fields array

void resetHiddenFields ()
setQueryOrder (line 1658)

Internal utility function - set order of the query according to filter.

void setQueryOrder (mixed &$q, mixed &$orderDef, mixed $defaultOrder)
standardEdit (line 1933)

A "standard edit" function.

It is quite complicated to provide handling of the edit form, since you must detect whether the user is here to edit record, or whether he just posted the values. When the values are posted, you have to try to apply them and show edit form again if there was an error. You also have to set several parameters for the calls. This method is here to take case of the most common case(s).

When script was called by the GET method, this prints edit form. When the script was called by POST, it tries to apply values and displays errors and the form again, when any error occurs. If values are applied OK, redirects to index script.

This method supposes id is passeded by get to edit.php and that it is either numerical with 0 meaning new record, or textual with empty string meaning new record.

void standardEdit (DBLQuery &$q, string $format, string $header, string $applyFormat, [array $err = array()])
  • DBLQuery $q: Query to use for getting/setting the values
  • string $format: Format to use to print the form.
  • string $header: Path to the file to be included as page header (may be PHP).
  • string $applyFormat: Format to use to apply the values. When it is empty, value of the $format parameter is used instead.
  • array $err: Errors from user check. Array of string. Each string is considered an error message (like those produced by fields). Can be used to nicely and simply show your own error messages.
submitButton (line 1012)

Formats submit button of the edit form.

It is here for you to override if you wish to have different button.

  • return: HTML of the button.
string submitButton (int $cols, int $dataSource)
  • int $cols: Number of columns the table has.
  • int $dataSource: Source of the record to edit. One of the DBL_FS_* constants.
tableStart (line 487)

Return table start (TABLE HTML tag)

This method should return table start HTML. It is here for you to override.

  • return: HTML of the table start.
string tableStart (int $style)
  • int $style: One of the DBL_FS_* constants
unauthorized (line 1986)

Prints unauthorized text.

This function is called when authorization check fails in some DBLView method. This implementation supposes the application prevents user from going where he should not be, so this is only a catch for cases where user directly enters URL of the page he does not have access to. (DBLIB itself does not make links to pages user does not have access to.)

You may want to override this function to get a nicer message than the provided one.

The function may either terminate script or return. If it returns, parent function will return too without doing anything.

void unauthorized (string $fromWhere)
  • string $fromWhere: fromWhere From where was the function called. Possible values are:
    • index
    • filter
    • edit
    • detail
    • applyValues

Documentation generated on Mon, 6 Sep 2004 21:57:19 +0200 by phpDocumentor 1.2.3