xdbgui.php Documentation

Documentation for the xdbgui.php file version 2.1

Contents

• Introduction
• class - CXDbGui

Introduction

xdbgui.php by Nigel Swinson.

+================================================================================================+
| A template class for creating a gui for an xdb
|
| To use this class, you "extend" it.  Create a new Constructor where you
| set up the class options, then create an instance of the class.  Call
| DrawJavascriptLinks() and DrawStyleSheetLinks() to render the static javascript/css
| content, then call RenderJavascript() and RenderStyleSheet to produce the
| dynamic javascript/css content.  The Javascript content should include a function that 
| will be used to display a record from a search result, and then call Main() in the main body 
| of the page.
|
| By default you will get a db that is capable of doing some rudimentary
| db operations like add/delete/search/list all, but in the likely event that
| you either want to add more operations, or adjust the existing ones, then you
| should override the existing methods from the base class, or define new ones.
|
| Specifically you are likely to want to override _DrawAddModifyForm()
| _ModifyRecord() and _DrawSearchForm() functions.  The class operates on
| the REQUEST vars.  The 'Action' holds what action is requested, and the other
| request vars are the parameters to that action.  Each action has a _HandleAction_...()
| member function associated with it that will be run by the Main().
|
+------------------------------------------------------------------------------------------------+
| Copyright:
|
| xdbgui.php: A template class for the construction of an PhpXDb gui
|
| Copyright (C) 2002-2003 Nigel Swinson, nigelswinson@users.sourceforge.net
|
| This program is free software; you can redistribute it and/or
| modify it under the terms of the GNU General Public License
| as published by the Free Software Foundation; either version 2
| of the License, or (at your option) any later version.
|
| This program is distributed in the hope that it will be useful,
| but WITHOUT ANY WARRANTY; without even the implied warranty of
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
| GNU General Public License for more details.
|
| You should have received a copy of the GNU General Public License
| along with this program; if not, write to the Free Software
| Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+================================================================================================+

Class CXDbGui

The CXDbGui class extends the CPage class.

• Public Methods
• Private Methods
• Public Methods Detail
• Private Methods Detail

Public Methods

• CXDbGui : Constructor
• Render : Renders the page
• DrawJavascriptLinks : Draws the javascript links for this page in <script src=?> elements
• DrawStyleSheetLinks : Draws the style sheets links for this page in <link> elements

Private Methods

You really shouldn't be raking about in these functions, as you should only be using the public interface. But if you need more control, then these are the internal functions that you can use if you want to get your hands really dirty.

• _RenderJavascript :
• _ToJavascript : Produce a call to the javascript DrawRecord function for the given object
• _DrawJavascriptLink : Draw a javascript link
• _DrawJavascriptInput : Draw a javascript input
• _CompileSearchFromFieldArray : Builds the XPathSearch from an array
• _CompileSearch : Builds the XPathSearch from the $_REQUEST
• _RecordsEqual : Determine if two records are equal
• _DiffRecords : Diff two records returning a string describing the differences
• _DrawFieldSortLink : Draw a link for a field that will sort the search results by that field.
• _DrawInputControl : Draws a input or textarea form control containing default text
• _Initialise : Obtains the configuration for the db gui
• _TuneActionsList : Disables/Hides all actions which are not permitted, and refines some of the action names
• _DrawActionsForm : Draw the form that gives access to the most common db functions
• _DrawIntroPage : The default action
• _Open : A wrapper for opening the database
• _Search : Search the database
• _ModifyRecord : Modifies the existing record in the database
• _DrawAddModifyForm : Draws the modify/add form
• _DrawSearchForm : Draws a search form.
• _HandleAction_Add : Handle the Add/Modify action
• _HandleAction_UpdateSelected : Update the selected fields for the selected items
• _HandleAction_DeleteRecord : Handle the DeleteRecord action
• _HandleAction_Search : Handle the Search action
• _HandleAction_ViewRecord : Handle the ViewRecord action
• _HandleAction_ListAll : Handle the ListAll action

Public Method Detail

Method Details: CXDbGui

---

function CXDbGui()

Constructor

Line:
Defined on line 156

	 Method Details: Render

function Render()
Renders the page
Overridden to close the db after performing all the actions
Line:
Defined on line 193

	 Method Details: DrawJavascriptLinks

function DrawJavascriptLinks()
Draws the javascript links for this page in <script src=?> elements
Overridden to include a js file for this class
Line:
Defined on line 215

	 Method Details: DrawStyleSheetLinks

function DrawStyleSheetLinks()
Draws the style sheets links for this page in <link> elements
Overridden to include a css link for this class
Line:
Defined on line 380

Private Method Detail

Method Details: _RenderJavascript

---

function _RenderJavascript()

Draws the javascript engine for the page either as raw content or in a <script> element 
depending on the ContentType.

The content will most likely contain a Javascript function that will be used 
to draw records.  This will be sent to the DB API SearchAndDisplay() which  
results in maximum compression of the resulting page for large searches, 
as each record only results in a single Javascript call, where the formatting is
done in the Javascript call.

The default version of this function will produce a function that draws
each record on a separate row, with every field drawn in a separate cell.

This approach will potentially be slow to render, because it will not know
how wide to draw each cell until it has closed the table at the end of the file.
So if you find that rendering searches takes a long time, then you should
consider re-writing this function to draw fixed width, independant entities.
This means the page can render as it downloads.

Return Value:

bool

TRUE on success, FALSE on failure.

Line:

Defined on line 248

Method Details: _ToJavascript

---

function _ToJavascript($RecordId, $aRecord)

Produce a call to the javascript DrawRecord function for the given object

Parameter:

			
array $aRecord
associative record array
			
int $RecordId
the record Id of the record
			
Return Value:
string
String of javascript
Line:
Defined on line 348

	 Method Details: _DrawJavascriptLink

function _DrawJavascriptLink($Action, $aAction)
Draw a javascript link
Draws some javascript which will render a link to the given details
Parameter:

			
string $Action
The name of the link, string that its output between <a></a>
			
array $aAction
Attributes of the link, an associative array containing:
 							'Name'	=> The name of the action as used on the gui.  If empty will use $Action
 							'Tooltip' => Tooltip string for the link
 							'Link' => Target for the link
			
Line:
Defined on line 409

	 Method Details: _DrawJavascriptInput

function _DrawJavascriptInput($Input, $aInput)
Draw a javascript input
Draws some javascript which will render an input control relating to the given details
Parameter:

			
string $Input
The name of the input, string that its output between 
			
array $aInput
Attributes of the link, an associative array containing:
 			'Name'		=> (string) The name of the input.  (Not necessarily the same as the key of 
 									the $aJavascriptInputs array).  If empty it will use the 
 									$Input instead
 			'Type'		=> (string) The type of the input
 			'Attributes'=> (string) If present, contains extra attributes to draw after the input.
			
Line:
Defined on line 437

	 Method Details: _CompileSearchFromFieldArray

function _CompileSearchFromFieldArray($aSearchInfo)
Builds the XPathSearch from an array
Uses the MatchType and the CaseSensitive REQUEST vars to combine the aSearchInfo
array into an XPath search string.
Parameter:

			
array $aSearchInfo
An associate array of name = value pairs that have
 									to be collated together
			
Return Value:
string
The XPath search string to use with the database
Line:
Defined on line 465

	 Method Details: _CompileSearch

function _CompileSearch()
Builds the XPathSearch from the $_REQUEST
Plucks out all of the REQUEST vars that correspond to field names and
then merges them together to produce an XPath search string.
Return Value:
string
The XPath search string to use with the database
Line:
Defined on line 531

	 Method Details: _RecordsEqual

function _RecordsEqual($aCurrentData, $aNewData)
Determine if two records are equal
Helper function for comparing records.
Return Value:
bool
Return TRUE if the records are identical, else FALSE.
Line:
Defined on line 564

	 Method Details: _DiffRecords

function _DiffRecords($aCurrentData, $aNewData)
Diff two records returning a string describing the differences
This function is particularly useful in reporting/logging changes made to the database
Return Value:
string
Return a string description in html of the changes between two user records
Line:
Defined on line 584

	 Method Details: _DrawFieldSortLink

function _DrawFieldSortLink($FieldName, $BaseUrl, $SortBy, $bReverseSortOrder, $Attributes='')
Draw a link for a field that will sort the search results by that field.
Draws a link for the given field name where if you click on the link
it will sort by that field and if you click again it will reverse the order.
An image will also be drawn on the right hand side of the link to indicate
the sort order.

This function will open and close the db.
Parameter:

			
string $FieldName
The title of the column
			
string $BaseUrl
The base url that all links should have to re-visit this page
			
string $SortBy
What we are currently sorting by.
			
bool $bReverseSortOrder
TRUE if we are reversing the sort order.
			
string $Attributes
Attributes for the link
			
Line:
Defined on line 623

	 Method Details: _DrawInputControl

function _DrawInputControl($FieldName, $aRecord=array(), $iMaxStringLen=0, $bMultiLine='', $Attributes='')
Draws a input or textarea form control containing default text
Overridden from the default in order to query the schema if no max length is supplied
Line:
Defined on line 650

	 Method Details: _Initialise

function _Initialise()
Obtains the configuration for the db gui
The default version of this function will programatically determine the name of
the table, record and field names and set other configuration accordingly.  All
this takes time so if you are authoring your own DB Gui, where the table name
and record name won't change, then you should consider overriding this function
and hard coding the values.

Additionally if there are other things that you need to initialise
before using the manager, like doing authentication against a database to determine
if the user can use the gui for example, then this would be the place to do it.
Return Value:
bool
TRUE on success, FALSE on failure.  On Failure, the function will have logged the error.
Line:
Defined on line 695

	 Method Details: _TuneActionsList

function _TuneActionsList()
Disables/Hides all actions which are not permitted, and refines some of the action names
Line:
Defined on line 808

	 Method Details: _DrawActionsForm

function _DrawActionsForm()
Draw the form that gives access to the most common db functions
This will produce a strip of buttons, one for each of the entries
in the aActions member array, excluding those secondary actions that
do not have the STYLE_MAIN property set.

The default version of this function draws only buttons, but you may wish
to override to have "quick access" elements in your form like Search forms with 
fields specifying IDs, or maybe First Names or something.
Line:
Defined on line 861

	 Method Details: _DrawIntroPage

function _DrawIntroPage()
The default action
The default version of this function will display the number of records in the
database and the last modified time.  If you have a database with many entries,
then you will want to override this function to avoid the search(*) operation
Return Value:
bool
TRUE on success, FALSE on failure.  On Failure, the function will have logged the error.
Line:
Defined on line 910

	 Method Details: _Open

function _Open($bWriteAccess = FALSE)
A wrapper for opening the database
You can specify if you want write access.  You can call this function
multiple times.
Parameter:

			
bool $bWriteAccess
Whether or not we need write access to the db
			
Return Value:
bool
TRUE on success, FALSE on failure.  The function logs it's own errors.
Line:
Defined on line 955

	 Method Details: _Search

function _Search($XPathSearch='true()', $SortByField='', $bReverseSortOrder = FALSE)
Search the database
This function will search the database, and draw the results using the Display()
method of the DB.

The default version of this function will draw the results in a table, which
may turn out to be a slow operation, as it will not know how to render the table
until it closes it.  For this reason if you find that the search results are
slow to render, then consider re-writing this function and the Javascript function
produced in DrawJavascriptDrawRecordFunction() to render the search results in
a more scalable fashion.

This function will open and close the db.
Parameter:

			
string $XPathSearch
What to search for
			
string $SortByField
What to sort by, defaults to the SortByField request var
			
bool $bReverseSortOrder
If we should reverse the sort order.  Defaults to
 								 the SortOrder request var, where if it is non empty, it
 								 will reverse.
			
Return Value:
bool
TRUE on success, FALSE on failure.  On Failure, the function will have logged the error.
Line:
Defined on line 982

	 Method Details: _ModifyRecord

function _ModifyRecord()
Modifies the existing record in the database
Modify an existing record, or add a new record, depending on the prescense of a
non-zero RecordId field.

The default version of this function will only permit you to set fields of the
existing schema, but it will not be able to do any further validation of the data.
It is for this reason that it is likely that you will want to override this function
to make sure that the business rules for your data are adhered to.  Like Names
must be in lower case with a capital first letter, or Telephone Number can't be blank
etc.  The default implementation also has no concept of duplicated records, so if you
override this function you can use the AddUniqueRecord() to make sure that you don't
have two records with the same "Name" or whatever else it is that you use as your
key to the database.
Return Value:
bool
TRUE on success, FALSE on failure.  On Failure, the function will have logged the error.
Line:
Defined on line 1116

	 Method Details: _DrawAddModifyForm

function _DrawAddModifyForm($RecordId = 0)
Draws the modify/add form
The default version of this function will draw a form containing text/textarea
inputs for all the fields of the record.  If you wish some of your fields to be
private and never displayed on a form (like a password) or for some to be <select>
tags, or to automatically generate some of the fields like making one a time, then
you will want to override this form.

This function will open the db if necessary.
Parameter:

			
int $RecordId
The record ID that we are modifying.  If not specified
 						   draws a blank "addition" form.
			
Return Value:
bool
TRUE on success, FALSE on failure
Line:
Defined on line 1192

	 Method Details: _DrawSearchForm

function _DrawSearchForm()
Draws a search form.
The default version of this function will draw a form containing text/textarea
inputs for all the fields of the record with a set of search options floating on
the right hand side of the form.  If you wish some of your fields to be <select>
tags, then you will want to override this form.

The default version of this function will permit you to search by
Line:
Defined on line 1288

	 Method Details: _HandleAction_Add

function _HandleAction_Add()
Handle the Add/Modify action
If called with only an add action, then it will draw a blank form.

If called with more than just an add action, then it will result in either
and add operation or a modify operation depending on whether or not the
RecordId is set in the request vars.

It is unlikely that you will want to override this action as it just
channels requests to _ModifyRecord() (which is probably what you want
to override.
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 1370

	 Method Details: _HandleAction_UpdateSelected

function _HandleAction_UpdateSelected()
Update the selected fields for the selected items
Return Value:
bool
TRUE on success, FALSE on failure
Line:
Defined on line 1433

	 Method Details: _HandleAction_DeleteRecord

function _HandleAction_DeleteRecord()
Handle the DeleteRecord action
Either draws a confirmation form, or Calls RemoveRecordId().

It is unlikely that you will want to override this action unless you have
data in other tables that must be deleted too.
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 1505

	 Method Details: _HandleAction_Search

function _HandleAction_Search()
Handle the Search action
Executes the requested search or if none has yet been requested, draws
the search form.

It is unlikely that you will want to override this action.
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 1564

	 Method Details: _HandleAction_ViewRecord

function _HandleAction_ViewRecord()
Handle the ViewRecord action
Draws a Modify form for the given record

It is unlikely that you will want to override this action.
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 1593

	 Method Details: _HandleAction_ListAll

function _HandleAction_ListAll()
Handle the ListAll action
It is unlikely that you will want to override this action.
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 1607