scripts.carrubbers.org home scripts@carrubbers.org
ExplorerIndex phpBanners PhpiCalLib PhpXDb Php.XPath SCMS
*

page.php Documentation

Documentation for the page.php file

Contents

Introduction

page.php by Nigel Swinson.

+================================================================================================+
| A base class for action driven web pages
|
| 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 CPage

Public Methods

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.

Public Method Detail

Method Details: CPage


function CPage()

Constructor

Line:
Defined on line 139

	 Method Details: Render

function Render()
Renders the page
Application pages tend to have a css layout component, a javascript client side engine
component, and an html content component.  The css and javascript can be sent once,
and then cached client side, whereas the html content is what changes on each page access
There may also be an AJAX version of the page content which is designed to be appended
to the foot of the existing page rather than a complete re-rendering of what has been drawn
already.

Derived classes need not use this method, they can instead call the public interface directly
to render html/javascript/css in one file.  If they do use this method, then they should supply 
_HandleContent_[ContentType] methods to handle each of the various content types.

It is unlikely that you will need to override this function
Return Value:
bool
TRUE on success, FALSE on failure.  On Failure, the class will have logged the error
Line:
Defined on line 179

	 Method Details: Main

function Main()
Renders the active content of the page
After initialising the class, it either calls _DrawIntroPage(), or performs the
required actions.  It is unlikely that you will need to override this function.
Return Value:
bool
TRUE on success, FALSE on failure.  On Failure, the class will have logged the error
Line:
Defined on line 207

function DrawJavascriptLinks()
Draws the javascript links for this page in <script src=?> elements
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 254

	 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.
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 272

function DrawStyleSheetLinks()
Draws the style sheets links for this page in <link> elements
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 328

	 Method Details: RenderStyleSheet

function RenderStyleSheet()
Draws the stylesheet for the page either as raw content or in a <style> element 
depending on the ContentType.
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 346

	 Method Details: htmlspecialchars

function htmlspecialchars($aArray)
Calls htmlspecialchars on each of an array's entry name and values.
If your array is solely for outputing to a web page, rather than for
control purposes, then you may find this version of htmlspecialchars
useful.
Return Value:
array
the new array
Line:
Defined on line 397
Private Method Detail

	 Method Details: _RenderJavascript

function _RenderJavascript()
Draw the actual javascript.
Called by RenderJavascript(), should just echo the javascript, the caller takes care of 
working out if <script> tags are needed
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 313

	 Method Details: _RenderStyleSheet

function _RenderStyleSheet()
Draw the actual css.
Called by RenderStyleSheet(), should just echo the css, the caller takes care of 
working out if <style> tags are needed
Line:
Defined on line 378

	 Method Details: _FindRealPath

function _FindRealPath($Path)
Returns a neat absolute path to the given path
Takes the given path, runs it through real_path.  If it can't find the path, it
will try prepending DOCUMENT_ROOT or the directory of this script.
Parameter:

			
string $Path
The path, to file or directory, that we want to locate

			
Return Value:
string
The path, cleaned up, or else '' if the file doesn't exist, with / rather than \
Line:
Defined on line 421

	 Method Details: _RealPathFromDocumentRoot

function _RealPathFromDocumentRoot($Path)
Returns a neat relative path from document root.
Takes the given path, runs it through real_path, then strips off the leading DOCUMENT_ROOT
Parameter:

			
string $Path
The path, to file or directory, that we want to clean up.

			
Return Value:
string
The path, cleaned up, or else '' if the file doesn't exist.
Line:
Defined on line 456

	 Method Details: _DirectoryList

function _DirectoryList($Dir, $aFiles, $Extension, $aExclusion)
get a complete directory and file list
Parameter:

			
string $Dir
base directory from DOCUMENT_ROOT

			
array $aFiles
an array of files already found

			
string $Extension
the extension we would like to look for

			
array $aExclusion
an array of strings for exclusion cases

			
Return Value:
array
directory listing
Line:
Defined on line 492

	 Method Details: _GrabContentType

function _GrabContentType()
Gets the content type we are currently rendering.
Return Value:
string
The content type we are rendering
Line:
Defined on line 539

	 Method Details: _GrabAsString

function _GrabAsString($Name)
If the given property is set in the REQUEST vars, then return it, else return ''
Parameter:

			
string $Name
The name of the request var we are intersted in.

			
Return Value:
int
'' if the request var does not exist, or is '' , else the string.
Line:
Defined on line 550

	 Method Details: _GrabAsInteger

function _GrabAsInteger($Name)
If the given property is set in the REQUEST vars, then return it, else return 0
Parameter:

			
string $Name
The name of the request var we are intersted in.

			
Return Value:
int
0 if the request var does not exist, is not an integer, or is 0, else the number.
Line:
Defined on line 562

	 Method Details: _GrabDate

function _GrabDate($FieldNamePrefix)
Obtain a date from the request vars.
To be used in conjunction with a set of form inputs built by the
_DrawDateAndTimeControls() method.
Parameter:

			
string $FieldNamePrefix
The prefix name of the select input controls

			
Return Value:
int
The corresponding unix epoch
Line:
Defined on line 577

	 Method Details: _StripSlashes

function _StripSlashes($aArray)
Strips slashes in all elements of the given array
Line:
Defined on line 602

	 Method Details: _DrawInputControl

function _DrawInputControl($FieldName, $aRecord=array(), $iMaxStringLen=0, $bMultiLine='', $Attributes='')
Draws a input or textarea form control containing default text
This function is called from the Add/Modify/Search forms.

The default version of this function will require access to the Schema
of the database which it will get by calling GetSchema().  This call
may be slow depending on the database implementation, so you may want
to override this function and index into a table to determine the field
width.
Parameter:

			
string $FieldName
The name of the text/textarea input control

			
array $aRecord
The record that contains the default value for this field

			
int $iMaxStringLen
The Maximum number of characters you want the input
 								  control to be, or 0 if you want it to query the schema to
 								  find the largest value.

			
bool $bMultiLine
TRUE if you want it to be a multiline control, FALSE if you
 								  want it to be an input control.  Unset if you want it to
 								  auto sense from the schema.

			
string $Attributes
Freeform string that is added to the select tag options

			
Line:
Defined on line 634

	 Method Details: _AsPotentialDate

function _AsPotentialDate($FieldName, $aRecord=array())
If the given field looks like a date(), then it will draw it as a date
Dates are stored as numbers, as this permits sorting, however when editing
dates you want to see what they are in terms of days months years etc.  This
function will analyse the given field, and if it looks like a sensible date
ie after 1990, then return it as a string.
Parameter:

			
string $FieldName
The name of the field containing the potential date

			
array $aRecord
The record that potentially contains the value for this field

			
Return Value:
string
A string describing the date, or '' if the field wasn't a date
Line:
Defined on line 678

	 Method Details: _DrawOptions

function _DrawOptions($aOptions, $Value='')
Draw a list of <option> elements for a <select> tag
Parameter:

			
array $aOptions
The options that we are going to draw

			
string $Value
The default value, that we should select

			
Line:
Defined on line 700

	 Method Details: _DrawSelectInput

function _DrawSelectInput($FieldName, $aRecord=array(), $aOptions, $Attributes='')
Draw a <select> tag with <options>
Parameter:

			
string $FieldName
The name of the select input control

			
array $aRecord
The record that contains the default value for this field
 								  if the default value isn't one of the $aOptions, then it will
 								  be added as an additional option to the control.

			
array $aOptions
The options that we are going to draw

			
string $Attributes
Freeform string that is added to the select tag options

			
Line:
Defined on line 727

	 Method Details: _DrawSelectInputFromAssoc

function _DrawSelectInputFromAssoc($FieldName, $aRecord=array(), $aOptions, $Attributes='')
Draw a <select> tag with <options value="key">value</option>
Parameter:

			
string $FieldName
The name of the select input control

			
array $aRecord
The record that contains the default value for this field
 								  if the default value isn't one of the $aOptions, then it will
 								  be added as an additional option to the control.

			
array $aOptions
An associative array of the options that we are going to draw.
 								 the key is the value, the value is the user visible option

			
string $Attributes
Freeform string that is added to the select tag options

			
Line:
Defined on line 753

	 Method Details: _DrawCheckboxControl

function _DrawCheckboxControl($FieldName, $aRecord=array(), $Attributes='')
Draw a <input type="checkbox">
Parameter:

			
string $FieldName
The name of the input control

			
array $aRecord
The record that contains the default value for this field
 								  if the default value isn't one of the $aOptions, or is zero/empty,
 								  then it will be unchecked.

			
string $Attributes
Freeform string that is added to the select tag options

			
Line:
Defined on line 787

	 Method Details: _DrawRadioButtonControl

function _DrawRadioButtonControl($FieldName, $Option, $aRecord=array(), $Attributes='')
Draw a <input type="radio">
Parameter:

			
string $FieldName
The name of the input control

			
array $aRecord
The record that contains the default value for this field
 								  if the default value isn't the $Option, then the radio won't be selected

			
string $Attributes
Freeform string that is added to the select tag options

			
Line:
Defined on line 804

	 Method Details: _DrawDateAndTimeControls

function _DrawDateAndTimeControls($FieldNamePrefix, $aRecord=array())
Draw a set of <select> inputs for a new date and time.
Parameter:

			
string $FieldNamePrefix
The prefix name of the select input control

			
array $aRecord
The record that contains the default value for this field
 									 if the default value isn't one of the $aOptions, then it will
 									 be added as an additional option to the control.

			
Line:
Defined on line 823

	 Method Details: _DrawDirectoryInput

function _DrawDirectoryInput($InputName, $DefaultValue='', $Attributes='')
Draw a parent directory control
Draws an input either containing the $InputName value and an open button, or
else if they have clicked the "open" button, the page is redrawn, and the input
becomes a select input containing all the sub directories, and again the open button.
Parameter:

			
string $InputName
The name of the input we are configuring.

			
string $DefaultValue
If the $InputName is not set in the _REQUEST vars, then
 								  use this as the InputValue.

			
string $Attributes
Freeform string that is added to the select tag options

			
Line:
Defined on line 875

	 Method Details: _GetThisPageUrl

function _GetThisPageUrl()
Return a URL to the current page.
Includes a trailing ? so that it is ready to append name=value pairs.
Return Value:
string
The URL to the current page.
Line:
Defined on line 928

	 Method Details: _Initialise

function _Initialise()
Obtains the configuration for the db gui
The default version of this function doesn't need to do very much, but it is
here mostly as a template for what you should do to write your own
Return Value:
bool
TRUE on success, FALSE on failure.  On Failure, the function will have logged the error.
Line:
Defined on line 954

	 Method Details: _TuneActionsList

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

	 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 1026

	 Method Details: _DrawLoadingPanel

function _DrawLoadingPanel()
Draw the loading panel we use while performing AJAX calls
Line:
Defined on line 1045

	 Method Details: _DrawActionButtons

function _DrawActionButtons($Mask)
Draw all the action buttons matching the given mask
Parameter:

			
Bitmask $Mask
Bitmask to use against the Style entry of the actions
 						  to decide if we should draw this action or not.

			
Line:
Defined on line 1063

	 Method Details: _DrawActionButton

function _DrawActionButton($aAction)
Draw an action button
Parameter:

			
array $aAction
The action to draw. An entry from the $this->aActions array

			
Line:
Defined on line 1080

	 Method Details: _PerformActions

function _PerformActions()
Peform any actions as required by the REQUEST vars
Retrieves the desired action from the REQUEST vars and calls the action handler.
It is unlikely that you will want to override this function
Return Value:
bool
TRUE on success, FALSE on failure.  On Failure, the function will have logged the error.
Line:
Defined on line 1103

	 Method Details: _DrawIntroPage

function _DrawIntroPage()
The default action
This function is called when no other action is specified.
Return Value:
bool
TRUE on success, FALSE on failure.  On Failure, the function will have logged the error.
Line:
Defined on line 1186

	 Method Details: _BuildLogRequestLine

function _BuildLogRequestLine()
Construct a string that we can use to log the request for this page
By default it will take $PHP_SELF and append to it all $_REQUEST[] in an encoded
format so that it will all go one one line.  But it may be that one of your request
vars is sometimes very long or of no interest, in which case it's wasted log space
that you want to ommit.  If so then override this function and exclude that variable
from the result.

Note you can also use this function to selectively disable logging for certain
requests.  If you examine the REQUEST vars and decide that you do not want to
log this one, then you can return an empty string, which will prevent logging
for this access.
Return Value:
string
The string that should appear as the "request" part of the logged result.  If it returns an empty string, then no log entry will be written.  The result can be multiline, but it will be encoded such that it appears in the log as one line.
Line:
Defined on line 1225

	 Method Details: _Log

function _Log($LogEntry)
Log a string to the log file
Log a string to the end of the log file.  Will open the log file if it isn't
open already.  You should call fclose($this->hLogFile) before the page quits.
Parameter:

			
string $LogEntry
The string to place in the log file.  If empty,
 							   nothing will be logged.

			
Return Value:
bool
TRUE on success, FALSE on failure
Line:
Defined on line 1252

	 Method Details: _LogRequest

function _LogRequest($bResult)
Logs the page request
If logging has been turned on, then calling this function will log all of the
request vars to document the page access.  It will call _BuildLogRequestLine()
to construct the actual request line that will get logged.  This function has
the opportunity to return an empty string to disable logging for that particular
page access.
Parameter:

			
bool $bResult
The result of the request.  Either TRUE or FALSE.

			
Return Value:
bool
TRUE on success, FALSE on failure.  On Failure, the function will have logged the error.
Line:
Defined on line 1277

	 Method Details: _DrawHiddenFormInputs

function _DrawHiddenFormInputs()
Draws hidden inputs which will result in the same base page being accessed
In the same way as ThisPageUrl can be used as the base for GET anchor links,
this function can be used to generate the default hidden options to supply any
additional parameters.

The default version of this function does nothing.  If your manager would manage
many different resources, or uses authentication input before accessing, then you
might want to override this function to provide that.
Line:
Defined on line 1349

	 Method Details: _HandleContent_Javascript

function _HandleContent_Javascript()
Renders the Javascript for the page.
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 1364

	 Method Details: _HandleContent_CSS

function _HandleContent_CSS()
Renders the CSS for the page.
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 1375

	 Method Details: _HandleContent_Ajax

function _HandleContent_Ajax()
Renders the Ajax for the page.
Return Value:
bool
TRUE on success, FALSE on failure.
Line:
Defined on line 1386

		
		

	

		
		
	
		

		
		

			Last updated: 17 April 2008 02:15:13.		

		
			© 2008 Carrubbers Christian Centre | Registered Charity No. SC011455

			Conditions of Use |
			Privacy Policy