Last update 3/1/2006
This class displays results of sql statements in a browseable and editable format akin to a MSAccess desktop display.
Version 4.1 adds database abstraction via the PEAR DB class. Please read about PEAR DB http://pear.php.net/manual/en/package.database.db.php. You can access database types other than MySQL by changing the database type variable. The simple connection functions included in the example scripts should be altered per the connection to be used, but will work in most cases. MySQL functionality remains the default and the class remains backwards compatable. Use the dbconnect() function for MySQL and dbconnectPEAR() for PEAR abstraction. The examples have been reworked to include the PEAR abstraction methods. This is not required if using MySQL methods in legacy scripts. Please review dbFunctions.inc to see the abstracted method code and PEAR DB Functions to examine the BrowseEdit implementation.
IMPORTANT: The identification of UID's for multiple tables has been changed. Please do not use the set_multiTable function. Instead set the column type attribute 'primaryKey' to TRUE. Multiple identical field names are now supported but must be distinguished using tablename.fieldname syntax. It is recommended to use tablename.fieldname syntax for all field references whether or not identical field names exist. In any case, do not mix syntax in the calling script.
IMPORTANT: Due to HTML limitations and addition of multiple tables, the HTML element name syntax has been changed to use 'table~field'. HTML will not post '.' so the ~ has been used as a delimiter instead. If you use HMTL element names in your scripts (Javascript,etc) then you will need to use the table~field syntax when referring to them. You should still use the table.field syntax in columnType and SQL instances.
Filtering has now been included in class. You can access filtering by <CTRL> clicking on the column header. A filter row with a dropdown of column distinct values will appear. Selecting a value will filter the result on that value. Turn off filtering by selecting __Filter Off__ in the dropdown.
Installation of PEAR DB: If you don't have PEAR installed please install PEAR per the PEAR website instructions. Make sure you include the path to the PEAR installation in your php.ini file. Install DB in the BrowseEdit directory. You will see a file DB.php and a folder DB.
Following the last major update (version 3) that was a result of a re-architecting of the column specification method for BrowseEdit, Version 4 adds multiple table select statements with updates on all tables. There are some additional features such as a checkbox that stores data in integer format, and 'alt' text for mouse hover on column titles. Please read this document thoroughly and the notes in the class and examples. While the class is backwards compatible in most respects with version 2, it is very important that you convert scripts to the new methodology. Future updates will not include the deprecated functions and these functions are not supported. Please read the section on class constructor, and set_columnType, as they are the heart of this class. All example scripts have been updated with the Version 3-4 methods. Please review them. They serve as a useful manual and are amply documented.
VERY IMPORTANT: THE ADDITION OF THE MULTIPLE TABLE SELECT HAS FORCED THE CALL OF THE UPDATE() and DELETE() FUNCTION TO FOLLOW SETTING COLUMN ATTRIBUTES. PLEASE ADJUST YOUR SCRIPTS ACCORDINGLY. SPECIFICALLY set_columnType($array) MUST PRECEDE UPDATE() or DELETE().
Please note that the example database has been expanded to include additional data, so please download and update.
The multiple table features allow any select statement that is updateable including inner joins, left and right joins, etc. Each table can be updated independently. Single table select statements will work identically as before. It is absolutely necessary to include 'table' for each field (table.field) and include each uid field for each table in multiple table sselect statements. Single table sql statements are not affected. You can hide the UID fields with the set_columnType function. The table and field used in instantiating the class will dictate the action of the 'select' column, and the order of table updates. For example, if deleteRecord() is called, the row in the table that is noted in the instantiation statement will be deleted, but not rows in the corresponding joined tables. Please read set_columnType PRIMARYKEY and set_multiDelimiter. -- New column type 'checkboxi' has been added. It stores on/off data as 1 and 0 instead of "on" and "" as 'checkbox' does. This adds some compatability with database features and TRUE FALSE statements.
-- Mouse hover text tags have been added with the 'alt' key in set_columnType, so that the user can place the mouse over a column header and get additional information.
-- Column header sorting capability is now on by default. The set_sortOrder function will override the default sort and any user selected sort. This is not backwards compatible. There is a new function to set the initial sort only: set_initialSort.
Version 3 added a dynamic value selectBox, a user-defined function, column display sequencing, among others. The “selectForm” option has been deleted, and a readonly form should be used in its place. The expansion of utilizing row data within action, selecting, and validating is available. Any MySQL row data and be inserted into a valid action string by enclosing the field name with “#” symbols. For example, an action column hyperlink:
$action=“<INPUT type=’button’ onClick=\”location=’test.php?email=#email#&contact_id=#contact_id#’\””;
The function column allows the programmer to define a function in the calling script and place the results of the function in the table. This is a very useful feature and allows almost unlimited data manipulation. Row data is sent to the function in a comma-separated array. See notes below and in the class and example 8.
The dynamic value selectBox feature allows the use of other table data and/or re-query of the main table to populate a drop-down list that changes for each row. Unfortunately, this column is not editable, due to the inherent complexity. However,javascript action can be added through the validation function
Addition of script definable character codes for character sets other than Latin1 is available through new function set_charCode.
Version 2 added features to include column types for date and datetime,textarea, radiobutton select of row with javascript insertion, action column for buttons, links andjavascript. Graphics added to show the sort order direction (available as http://www.thinktrain.com/browse_edit/arrow_plain_up.gif and http://www.thinktrain.com/browse_edit/arrow_plain_down.gif . New functions are highlighted in this document.
The following features are included:
Included files: ALL NEW FOR VERSION 4 - if you are new to BrowseEdit, examine each example file in the order shown
Database name for the examples is 'example' and can be reconstructed from example.sql
Make sure you change the password and username in the example scripts in order to connect to the example database.
I have received many comments and suggestions for BrowseEdit, and I want to thank all those who have contributed and those who will contribute to the usefulness of this class. Please feel free to comment or make suggestions. Also, if you are using the class in a publicly accessible script and would like to show it off, let me know.
Released under GNU public license
Direct all comments to Peter Rosomoff
| Class Constructor | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| BrowseEdit – class constructor function | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void BrowseEdit(string tablename, string uid, [[string sql,string formname]]) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Creates an instance of the class BrowseEdit that supports all features and functions. Tablename and the Unique Identifier field name (uid) are mandatory. Default sql statement created is "SELECT * FROM tablename ORDER BY uid". Optionally you can provide an explicit SQL query string as long as the uid is included in the result. Multiple table select statements can also be explicitly provided. The designated tablename and uid are used in update and delete functions, as well as being the first table to be updated. IT IS ABSOLUTELY NECESSARY TO INCLUDE 'TABLE' FOR EACH FIELD (TABLE.FIELD) AND INCLUDE EACH UID FIELD FOR EACH TABLE IN MULTIPLE TABLE SSELECT STATEMENTS. Please read set_multipleTable and set_multiDelimiter. You can also provide a name for the form to provide differentiation from other forms on the same page. Default is "mainForm". Note: UID fields are set to readonly by default and can be enabled with set_columnType although this is not recommended, I strongly suggest using an autoincrement UID field whenever possible
Parameters:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __construct – class constructor function extending BrowseEdit (PHP5) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void __construct(string tablename, string uid, [[string sql,string formname, string usePear, object pearDB]]) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Creates or extends an instance of the class BrowseEdit that supports all features and functions. Called by BrowseEdit.
Parameters:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Multiple Table SQL Functions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_multipleTable – Designates multiple sql statement tables and UID fields DEPRECATED - see set_columnType PRIMARYKEY | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_multipleTable(array multi) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| This function must be called when using multiple table sql. The single parameter is an array with the key as the table name, and the value as the UID field for that table. BrowseEdit will update tables in the following order: table designated in the class instantiation then the array order of parameter provided to set_multipleTable. BrowseEdit is not 'referential integrity' aware. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_multiDelimiter – Set the row UID delimiter character | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_multiDelimiter(string delim) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets the delimiter character for the row UID. Default is ';'. You only need to change this delimiter is if the data in the UID fields contains ';'. The row UID is created by concatenating the UID field values from the table(s) delimited by the delimiting character. This creates a unique identifier for each display row. If the data has the delimiting character in the UID field value, it will confuse the class and updates and deletes could act unpredictably. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Display Scope Functions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_charCode – Set character code used in htmlentities | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_charCode(string code) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Sets the character code used in htmlentities function. Defaults to ISO-8859-1.
Charset Aliases Descriptions:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_ColumnType – Set column/field attributes | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_columnType(array col) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_counter() – displays a incremented line counter | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_counter() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Displays an incremented line counter for each row | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set _defaultColType – sets column type default for columns not specified in set_columnType | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_defaultColType(string type) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets the default type of column for columns that have not been specified by set_columnType. Type default is text. Default can be changed with this function to hidden, checkbox, or textarea. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_displayOnly – turn off editing capability | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_displayOnly() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Turns off editing capability by making fields readonly | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_footer – sets the footer HTML | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_footer(string text) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets the footer HTML that will be inserted between the table close tag and the form close tag. Ideal for action buttons like add, delete, save, etc. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_initialSort – sets initial sort for the display | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_initialSort(string sort) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets the initial sort order for the display. Do not specify the sortorder in explicit SQL. Use this function. You should include 'ASC' or 'DESC' in your value. See examples. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_maxPageShow – Sets number of pages to show in navigation bar at one time | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_maxPageShow(int) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets number of pages to show in navigation bar at one time. Only functional if set_pagingOn is called. Default is 5. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_pagingOn – Turns on paging feature | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void setpagingOn() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Allows paging of large results with navigation links. Works with set_maxPageShow and set_recsPerPage | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_recsPerPage – Sets number of records to show in single screen | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_recsPerPage(int) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets number of records to show in a single screen. Only useful if set_pagingOn is called. Default is 10 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_selectedRow – pre-selects row on initial display | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_selectedRow(string UID) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets the radio button or checkbox for the row identified by UID as selected | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_sortOrder – sets and overriding sort for the display | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_sortOrder(string fieldname) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets the sort order for the display that can override user and default values. Do not specify the sortorder in explicit SQL. Use this function. You should include 'ASC' or 'DESC' in your value. See examples. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_title – sets the title for the display | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_title(string text) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets the title of the display after the opening form tag as the first row of the table. Any HTML is acceptable. Ideal for action buttons etc. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_userRecsPerPage – Sets user interface for number of records displayed | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_userRecsPerPage() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Turns on display of text box for user to enter how many records per page to display. Default of 10 can be changed with set_recsPerPage | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Column Scope Functions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_noSelectColumn – Prevents select column display | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_noSelectColumn() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Prevents the select column from displaying | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_radioButton – Sets select column (leftmost column) to radio button instead of checkbox (default) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_radioButton() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets select column (leftmost column) to radio button instead of checkbox (default). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_selColumnAlt – sets the alternate text for the select column. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_selColumnAlt(string text) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets the alternate text for the select column which can be displayed when the user hovers mouse over the select column header. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_selColumnName – Sets text for select column header | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_selColumnName(string text) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Set the select column header text (default ‘Sel’) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_selectAction – Sets action to be taken when select button is clicked (javascript). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_selectAction(string javascript) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets select column action as a javascript string. Row data may be used | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Formatting | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_arrowPath – sets a path for sorting arrow images | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_set_arrowpath(array array) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets the complete pathname from the executing script to the arrow images for sorting. Array has two members with keys 'ASC' and 'DESC' whose values are the full path names. Be sure to use appropriate slashing or addslashes when creating the full path names. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_bgcolor – Sets background color for table | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_bgcolor(string string) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets background color for main table. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_disabled_bg – Sets the field background color for disabled fields | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_disabledbg() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets the field background color for disabled fields. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_fontFamily – sets the font family | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_fontFamily(string text) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets the font family for the table display. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_fontSize – sets the font size for the display | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_fontSize() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets the font size for the display. Default is 8pt. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_rowcolor – Sets colors for odd and even display rows | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_rowcolor(string, string) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sets color (hexadecimal or HTML color name) for odd and even display rows. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set_showtable – Inserts TABLE tag to access table formatting. Advanced users only. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void set_showtable(string) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Inserts TABLE tag to access table formatting. Advanced users only. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Utility Functions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| addRecord – add a blank record to the table | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void addRecord() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Adds a blank record to the table with null values, then refreshes the display | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| deleteRecord –delete the selected record(s) from the table | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void deleteRecord(mixed variable) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Deletes the selected record(s) from the table and resets the display. (NEW) Input must be for row uid and can be array or single variable. Typically will be $_POST['selRecord'] from the select column. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| display – main display function | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void display() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Displays the form | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| doQuery – execute sql statement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| int doQuery(string sql) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Executes query and returns result ID. Provides error trapping. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updateRecord – Saves any changed information to the database | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| void updateRecord() | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Creates and executes an SQL update query to permanently store form changes into the database. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| PEAR DB Functions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| num_rows – Substitute for mysql_num_rows | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| num_rows(object result) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| fetch_array – Substitute for mysql_fetch_array | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| array fetch_array(object result) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| fetch_row – Substitute for mysql_fetch_row | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| array fetch_row(object result) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| num_fields – Substitute for mysql_num_fields | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| int num_fields(object result) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| field_name – Substitute for mysql_field_name | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| string field_name(object result, int offset) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| fetch_field – Substitute for mysql_fetch_field - only returns array of table and field name NOT an object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| array fetch_field(object result) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| data_seek – Substitute for mysql_data_seek | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| data_seek(object result, int pointer) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| free_result – Substitute for mysql_free_result | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| free_result(object result) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||