<?
/*******************************************************************/
class result
{
/*===================================================================
CLASS SUMMARY
Class Name: result
Author: jestevez
Created on: 5/22/00 4:09 PM
Last Change: 6/15/00 9:33 PM
Version: 0.1 This is a beta.
For complete documentation, please see the Result Class User Guide.
Things you need to change...
(1) Property: $path_to_templates
(2) Constructor: result()
(3) Method: parse_rule_element()
You can find them by looking for CHANGE in the code below.
===================================================================*/
// PROPERTIES
// CHANGE (1)
// You must set the value below to the path to your result templates. The path must end with '/'.
var $path_to_templates = ''; // String. The path to your result class templates.
var $result_id = FALSE; // Boolean A db result id passed to the contructor.
var $debug = FALSE; // Boolean If TRUE, messages will output to screen.
var $num_rows = 0; // Integer Number of returned DB as referenced by result id.
var $offset = 0; // Integer The default offset.
var $all_rules = array (); // Array Holds all rules.
var $html_buffer = ''; // String Buffers HTML for return.
var $dominant_rule = ''; // String Which ever rule correctly specifies the num_rows.
/*=================================================================*/
// CONSTRUCTOR
function result ( $result_id )
// Use the result_id to get the number of rows.
// If the result_id isn't set or is false, kick an error.
// 5/28/00 10:31 AM by Pippen
{
if ( $result_id )
{
$this->result_id = $result_id;
// CHANGE (2)
// Change the line below one that works with your database!
// The line should return the number of rows associated with the passed $result_id.
$this->num_rows = db_numrows ( $this->result_id );
return ( TRUE );
}
// You might want to set an error here: set_error ( DB_ERROR, 'Result class passed a result_id that was not valid.' );
}
/*=================================================================*/
// METHODS
/*-----------------------------------------------------------------*/
function set_result_rule ( $rule )
// 6/6/00 9:13 AM by jestevez
// Take the rule and see if it specifies a test.
// If it does, run the test and return false if the test is not passed.
// Otherwise, add the control.
// The return value is not significant to the class, but may
// be useful to the programmer.
{
// Check to see if the input is an array: assert_array ( $rule );
$is_test = in_array ( 'test', array_keys ( $rule ) );
$test_OK = $rule['test'];
if ( $is_test and ! $test_OK )
{
return ( FALSE );
}
$name = $rule['name'];
$this->all_rules[$name] = $rule;
return ( TRUE );
}
/*-----------------------------------------------------------------*/
function unset_result_rule ( $rule_name, $test = 1 )
// 6/6/00 9:13 AM by jestevez
// If the test passes, delete the rule.
// The default test always passes.
// The return value is not significant to the class, but may
// be useful to the programmer.
{
if ( ! $test )
{
return ( FALSE );
}
unset ( $this->all_rules[$rule_name] );
return ( TRUE );
}
/*-----------------------------------------------------------------*/
function get_result_html ( )
// Find a rule that applies to the number of rows returned.
// Apply that rule.
{
$num_rows = $this->num_rows;
$this->debug ( "Num rows is $num_rows." );
foreach ( $this->all_rules as $rule_name => $rule_value )
{
$max = (int) $rule_value['max'];
$min = (int) $rule_value['min'];
$redirect = (string) $rule_value['redirect'];
if ( $min <= $num_rows and $num_rows <= $max )
{
// If we are inside this clause it is because we found a rule that
// applies to the number of results returned by result_id passed to the class.
// Some rules ask us to redirect.
if ( $redirect )
{
// This will not work if any output has already been sent to the browser.
header ( "Location: $redirect" );
exit;
}
$this->dominant_rule = $rule_value;
$this->apply_dominant_rule ( );
break; // ... because only one rule should be used.
}
}
return ( $this->html_buffer );
}
/*-----------------------------------------------------------------*/
function include_template ( $template )
// In order to include elements, we need to first include their parent template.
// If we can't include the parent template, we're in trouble, so kick errors.
// 5/26/00 2:30 PM by jestevez
{
// IMPORTANT: Change the line below to point make sure it points to your template.
$template_path = $this->path_to_templates . $template . '.tpl';
if ( ! is_readable ( $template_path ) )
{
$this->debug ( "Error trying to use template $template_path" );
// Put in code to log error?
return ( FALSE );
}
include ( $template_path );
$this->debug ( "Template '$template' is OK" );
return ( TRUE );
}
/*-----------------------------------------------------------------*/
function debug ( $message )
// If debugging is on, output a debugging message.
// 5/26/00 4:56 PM by jestevez
{
if ( $this->debug )
{
print ("<BR><B>Result Class Debugging:</B> $message.");
}
}
/*-----------------------------------------------------------------*/
function parse_rule_element ( $element, $arguments, $type = '' )
/*--------------
NOTE: This function is recursive in 2 ways.
i. It keeps calling itself until the $element passed is not an array.
ii. If the element passed needs data from the DB,
the function gets that data, adds it to the $arguments,
and calls itself again.
5/26/00 2:51 PM by jestevez
--------------*/
{
if ( is_string ( $type ) AND $type == 'data' )
{
// This element expects data from the database.
// Loop through the data from the db, merge it with any rule specified $arguments.
// For each row, send the element back to this function,
// but this time, set type to 0 so no data is fetched from db.
// But before we actually loop through the data, lets put up
// control the widgets that let the user 'page' through results from a query.
$this->prepare_scroll_controls ();
$offset = $this->offset;
$last = $this->last;
$this->generate_scroll_controls ();
$this->debug ( "Offset is $offset." );
$this->debug ( "Last is $last." );
for ($i = $offset; $i < $last; $i++ )
{
// CHANGE (3)
// Change the call to db_fetch_array to one that
// returns an assoc array of col names and values of the row $i of your db result!
$row = db_fetch_array($this->result_id, $i, PGSQL_ASSOC );
$element_arguments = array_merge ( (array) $arguments, (array) $row );
$this->parse_rule_element ( $element, $element_arguments, '' );
unset ( $element_arguments );
}
// unset ( $type );
return ( TRUE );
}
// If we've gotten this far then $arguments has any data needed from DB.
// We are now free to go ahead and process the element.
if ( is_array ( $element ) )
{
foreach ( $element as $this_element )
{
$this->parse_rule_element ( $this_element, $arguments, $type );
}
return ( TRUE );
}
// If we have gotten this far, then $element has complete $arguments
// and is not an array. We can now include the element.
// To include an element we need to know which template it is in,
// so get the template name and then include the element.
// Some elements might specify a template.
// If they do, they are of form "template.element".
// If that is the case, then break the element apart into $template and $element.
// If that isn't the case, use the template set by the dominant rule.
if ( strstr ( $element, '.' ) )
{
list ( $template, $element ) = explode ( '.', $element );
}
else
{
$template = $this->dominant_rule['template'];
}
$fully_specified_element = $template . '_' . $element;
// If the function isn't defined, we need to include the template for it.
if ( ! function_exists ( $fully_specified_element ) )
{
// The rule format depends on functions in the rule template.
// So, we have to try to include the template.
// If we can't, we have a problem.
if ( ! $this->include_template ( $template ) )
{
return ( FALSE );
}
}
$this->include_element ( $fully_specified_element, $arguments );
return ( TRUE );
}
/*-----------------------------------------------------------------*/
function include_element ( $fully_specified_element, $arguments )
/*--------------------------------
6/13/00 4:05 PM by jestevez
Execute a template function ( a $fully_specified_element )
and send any returned values to HTML buffer.
Arguments includes any info from the database
and any explicit arguments specified by a rule.
All content comes through this function.
--------------------------------*/
{
if ( function_exists ( $fully_specified_element ) )
{
$this->debug ( "Including element $fully_specified_element.");
$this->html_buffer .= $fully_specified_element ( $arguments );
return ( TRUE );
}
$this->debug ( "Element $fully_specified_element does not exist." );
// Put in code to log error?
return ( FALSE );
}
/*-----------------------------------------------------------------*/
function apply_dominant_rule ( )
// Use the dominant rule to return HTML.
// 5/22/00 4:09 PM by psuda
{
$rule = (array) $this->dominant_rule;
$name = (string) $rule['name'];
$template = (string) $rule['template'];
$format = $rule['format'];
$arguments = $rule['arguments'];
$this->debug ( "Applying rule \"$name\"" );
// The rule format specifies which functions of the template to use.
// Take the format elements one at a time and parse them.
// This is where they have a chance to generate output, talk to database, etc...
foreach ( $format as $type => $element )
{
$this->parse_rule_element ( $element, $arguments, $type );
}
}
/*-----------------------------------------------------------------*/
function generate_scroll_controls ( )
// This function produces links "Next" and "Prev"
// which let the user "scroll" through a set of results.
// 6/7/00 12:04 PM by jestevez
{
$offset = $this->offset;
$num_rows = $this->num_rows;
$rule = $this->dominant_rule;
$scroll_args = $rule['scroll_args'];
$limit = $this->limit;
// If there is no limit, we don't need no stinkin' scroll controls.
if ( ! $limit )
{
return ( TRUE );
}
// If the total number of rows is less than the limit, we don't need no stinkin' controls.
if ( $num_rows < $limit )
{
return ( TRUE );
}
// Scroll arguments will be appended to the "next" and "prev" links.
// Passing the query is too dangerous, so we pass along variables that the page will use
// to reassemble the query. Collectively we call these the 'scroll args'.
// Not all pages will have scroll arguments, so only build them if there are some.
if ( count ( $scroll_args ) )
{
foreach ( $scroll_args as $name )
{
// We only grab values from global scope,
// because all url values get dumped to global scope anyway.
global $$name;
$value = $$name;
$buffer[] = $name . '=' . urlencode ( $value );
}
$scroll_args = implode ( '&', $buffer );
}
// Build "Next" link.
if ( $offset + $limit < $num_rows )
{
// If we don't get here, there are no more results to show, so no link.
$next_offset = $offset + $limit;
$next_link = '[' . html_a ( "?offset=$next_offset&$scroll_args", 'Next' ) . ']';
}
// Build "Prev" link.
if ( $offset - $limit > -1 )
{
// If we don't get here, there are no results in front of the current results, so no link.
$prev_offset = $offset - $limit;
$prev_link = '[' . html_a ( "?offset=$prev_offset&$scroll_args", 'Prev' ) . ']';
}
// Figure out the current rows being displayed.
$first = (string) $offset + 1;
$last = (string) $offset + $limit;
// Adjust $last to handle the "end" exception.
if ( $last > $num_rows )
{
$last = $num_rows;
}
// Handle the case where first = last.
if ( $first == $last )
{
$first_last_message = "<b>result $first</b>";
}
else
{
$first_last_message = "results <B>$first to $last</b>";
}
//Take the final message and add it to the result HTML buffer.
$message = "Showing $first_last_message [of $num_rows found]";
$this->html_buffer .= "<P>$prev_link $message $next_link<P>";
}
/*-----------------------------------------------------------------*/
function prepare_scroll_controls ()
// To loop through db results we need an offset and a last row.
// The last row is based on the limit.
// So, we get an offset and limit first. They are used to get the last row.
{
$this->get_offset ();
$this->get_limit ( );
$this->get_last ( );
}
/*-----------------------------------------------------------------*/
function get_offset ( )
// Get a safe value for an offset.
// If there is no offset, set it to 0.
{
$offset = $this->dominant_rule['offset'];
if ( $offset == '' )
{
$offset = 0;
}
$this->offset = $offset;
}
/*-----------------------------------------------------------------*/
function get_limit ( )
// Figure out a safe value for a limit.
// We don't want to go past num_rows.
{
$limit = $this->dominant_rule['limit'];
if ( $limit == '' )
{
$limit = $this->num_rows;
}
$this->limit = $limit;
}
/*-----------------------------------------------------------------*/
function get_last ( )
// Figure out the last row of results to display.
// Make sure the last row is not greater than the total number of rows.
{
$offset = $this->offset;
$limit = $this->limit;
$num_rows = $this->num_rows;
if ( $offset + $limit > $num_rows )
{
$last = $num_rows;
}
else
{
$last = $offset + $limit;
}
$this->last = $last;
}
/*-----------------------------------------------------------------*/
}
/*******************************************************************/
?>
|
Download
