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:
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)
Constructor.
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.
Adds hidden field
Adds new hidden value (hidden type field) to the view. All hidden fields will be placed in the edit form.
Formats apply button of the fliter form.
It is here for you to override if you wish to have different button.
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:
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.
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.
Formats clear/reset button of the fliter form.
It is here for you to override if you wish to have different button.
Print out record detail.
Important!
Format detail auto references.
It is here for you to override.
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 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 how to end record detail table row.
It is here for you to override.
Return how to start record detail table row.
It is here for you to override.
Print out edit form.
Important!
Format edit auto references.
It is here for you to override.
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 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 how to end edit record form table row.
It is here for you to override.
Return how to start edit form table row.
It is here for you to override.
Formats field to be shown in the record detail.
You may want to override this if you want "special effects" in the detail.
Formats field to be shown in the edit form.
You may want to override this if you want "special effects" in the form.
Formats field to be shown in the filter form.
You may want to override this if you want "special effects" in the form.
Formats field to be shown in the index
You may want to override this if you want "special effects" in the index.
Print out filter form and apply filter to the query.
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 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 how to end filter form table row.
It is here for you to override.
Return how to start filter form table row.
It is here for you to override.
Formats index record.
You may want to override this if you want "special effects" in the index.
Show record index.
Important!
This method prints out HTML for the record index.
Format index auto references.
It is here for you to override.
Return index column title.
Internal function
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 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 how to end index table record.
It is here for you to override. (Default implementation returns row end.)
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 how to end index table row.
It is here for you to override.
Return how to start index table row.
It is here for you to override.
Formats order combo (and the 'reverse' checkbox too).
Override this if you wish to have different combo/checkbox.
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).
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.
Prints out error message (after a POST error).
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.)
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).
Reset the hidden fields array
Internal utility function - set order of the query according to filter.
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.
Formats submit button of the edit form.
It is here for you to override if you wish to have different button.
Return table start (TABLE HTML tag)
This method should return table start HTML. It is here for you to override.
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.
Documentation generated on Mon, 6 Sep 2004 21:57:19 +0200 by phpDocumentor 1.2.3