EZ Results Help Documentation

PLEASE READ THIS DOCUMENT IN FULL BEFORE EMAILING FOR HELP

Class Features

Makes it fast and easy to display DB results on your website
You can manipulate results before they have been displayed
All result formatting is completely customisable
Automatically builds result navigation links
Works with mySQL or Oracle
Saves hours of programming
Much, much more..

Quick Example

// EZ Results requires ezSQL (available from www.jvmultimedia.com)

include_once “ez_sql.php”;

// Include the EZ Results Class

include_once “ez_results.php”;

// Perform query and display results

$ezr->query_mysql(“SELECT email, login FROM users”);

$ezr->display();

Introduction

I have been meaning to create a results navigation class for some time now. Mainly because

just about every site I work on needs to display database driven results. When architecting

this class I had the following requirements in mind:

Enable prototyping of results driven web page(s) within a few minutes
Allow me to minutely tweak all aspects of the HTML formatting
Enable me to manipulate the results before displaying them
Be able to display results as an HTML table or standard HTML list
Must be a small class with small code overhead
Must have built in result navigation

I’m glad to say all these requirements have been met!

In order to facilitate the above I decided to move away from template concepts (e.g static file

templates) and make the whole thing dynamic, therefore this class is most suited to

developers who are familiar with programming PHP with a text editor and may not be the

best choice for use with HMTL design packages such as Dreamweaver.

How it works

In psudo-code the way the class works is like this:

Tweak various variables within the class to control output format
Supply a well formed query to the class
Issue a command to display results

In real code it looks something like this:

$ezr->num_results_per_page = 10;

$ezr->results_heading = “<tr><td colspan=2>My Results</td></tr>”;

$ezr->results_row = “<tr><td>email: COL1</td><td>login: COL2</td></tr>”;

$ezr->query_mysql(“SELECT email, login FROM users”);
$ezr->display();

How Data Is Merged

COL1, COL2, COL3, etc.. are special symbols (specific to $ezr->results_row). During script

execution these symbols are replaced with your dynamic content – i.e. COL1 will be replaced

with the content in column 1, COL2 replaced with the content in column 2 and so on.

Here is a full list of variables that make use of special symbols to merge data.

EZ Results Variable	Example Symbol Usage	Output
$ezr->results_row	<tr><td>COL1</td></tr>	<tr><td>My Data</td></tr>
$ezr->results_row	<tr bgcolor=ALTCOLOR1> ALTCOLOR2, ALTCOLOR3	<tr bgcolor=ffffff> (for alternating row colors – you may have up to three pairs)
$ezr->text_count	NUMBER Results	345 Results
$ezr->text_next	Next NUMBER >>	Next 20 >>
$ezr->text_num_pages	(NUMBER Pages)	(16 Pages)
$ezr->text_back	<< NUMBER Back	<< 20 Back
$ezr->text_last_page	[last of NUMBER pages]	[last of 6 pages]
$ezr->mixed_nav_left	Browsing CUR_START-CUR_END of TOTAL_RESULTS results (page CUR_PAGE of NUM_PAGES pages)	Browsing 1-5 of 256 results (page 1 of 25 pages)
$ezr->mixed_nav_right	Browsing CUR_START-CUR_END of TOTAL_RESULTS results (page CUR_PAGE of NUM_PAGES pages)	Browsing 1-5 of 256 results (page 1 of 25 pages)
$ezr->text_hover_msg_link	Goto page NUMBER of results..	Goto page 10 of results..
$ezr->text_hover_msg_next	Goto next NUMBER of results..	Goto next 10 of results..
$ezr->text_hover_msg_back	Goto previous NUMBER of results..	Goto previous 10 of results..

Formatting Results

For most of your result formatting needs the following variables should be sufficient:

$ezr->results_open

$ezr->results_heading

$ezr->results_row

$ezr->results_close

$ezr->results_empty

If you would like your results displayed within a simple table you might do the following:

$ezr->results_open = “<table>”;

$ezr->results_heading = “<tr><td colspan=2>My Results</td></tr>”;

$ezr->results_row = “<tr bgcolor=ALTCOLOR1><td>COL1</td><td>COL2</td></tr>”;

$ezr->results_close = “</table>”;

$ezr->results_empty = “<b>Sorry. No results!”;

$ezr->query_mysql(“SELECT email, login FROM users”);

$ezr->display();

If you would like your results displayed as a list, i.e. not using a table, you might do the following:

$ezr->results_open = “<ul>”;

$ezr->results_heading = “<b>My Results..</b>”;

$ezr->results_row = “<li>COL1 - COL2”;

$ezr->results_close = “</ul>”;

$ezr->results_empty = “<ul><b>Sorry. No results!</ul>”;

$ezr->query_mysql(“SELECT email, login FROM users”);

$ezr->display();

Note: There are a number of other variables that can be used to tweak your result formatting.

To find out more about them see the Results Formatting reference below.

Formatting Navigation Links

There are quite a few formatting options for navigation links. They have been split up into navigation link components.

365 Results: [start] << 1 2 3 4 5 >> [last of 22]

In the above example the ‘result count’ component has been highlighted in red. It is controlled

by the following variables.

$ezr->show_count – turn the component on/off

$ezr->text_count – the actual text displayed

$ezr->style_count – css formatting for the component

$ezr->class_count – assign the component to a css class

If you did not want to show the ‘result count’ at all you would simply do the following:

$ezr->show_count = false;

$ezr->query_mysql(“SELECT email, login FROM users”);

$ezr->display();

Each components formatting can either be controlled by css style syntax or it can simply be

assigned to a css class (which overrides the first option). Here is an example of formatting the

‘result count’ component by directly inputting css syntax.

$ezr->text_count = ‘NUMBER Results’;

$ezr->style_count = ‘font-family: Verdana; font-size: 10pt;’;

$ezr->query_mysql(“SELECT email, login FROM users”);

$ezr->display();

Here’s how to assign it to a css class (thus allowing you to do all your formatting in css style

sheets).

$ezr->text_count = ‘NUMBER Results’;

$ezr->class_count = ‘my_class’;

$ezr->query_mysql(“SELECT email, login FROM users”);

$ezr->display();

Note 1: For a full list of formatting options see the Navigation Formatting reference below.

Note 2: If you want completely unlimited navigation formatting then turn off all other

navigation variables except for $ezr->mixed_nav_left & $ezr->mixed_nav_right see the

reference table below for further information about these.

Manipulating Results

In order two manipulate results there are a few concepts that must be understood:

1) Results can only be manipulated by functions that you create external the $ezr object.

2) You must register each function using $ezr->register_function()

3) Your function(s) are called just before each row is displayed.

4) Each rows contents is dynamically passed to your function(s).

5) Thus allowing you to manipulate each row/column before it is displayed.

Note: For a full explanation of how to manipulate results see the notes about

$ezr->register_function() (in the function reference below).

Using EZR Templates

The easiest way to deal with multiple result set pages on your site, all of which require

different formatting, is to use EZ Results Templates. An EZR template is simply a PHP file

that contains (and sets) ALL formatting variables. To use a template is as simple as this:

include_once “sample_template.php”;

$ezr->query_mysql(“SELECT email, login FROM users”);

$ezr->display();

Note 1: There is a sample template contained within the ezr folder.

Note 2: If you just have one type of look and feel on your website there is probably no need to

use templates. More often than not the only change from one results set to the next is the

number of columns you will be displaying. Therefore, when working this way, it is best to

simply change the default values, in the actual class itself, and then simply change the

following two variables each time you call EZ Results:

$ezr->results_heading = “<b>My Results..</b>”;

$ezr->results_row = “<li>COL1 - COL2”;

Getting Started

Make sure that you read all of the above! If you don’t you will find yourself getting frustrated

rather quickly. Once that’s done try running ez_results_demo.php. To do that you will need

to open it in your favourite text editor and change some self explanatory values at the top.

Once you have it up and running have a look at the code which should make things clear.

Also, keep this document to hand as you will need the below function and formatting

references to make the most of EZ Results.

All that remains for me to say is good luck and happy formatting!

Justin Vincent

info@jvmultimedia.com

FUNCTION LIST

User Functions

$ezr->query_mysql()– Submit query (if using mySQL database)

$ezr->query_oracle() – Submit query (if using Oracle database)

$ezr->get() – Gets the final output (as returned value)

$ezr->display() – Prints the final output to screen

$ezr->set_qs_val() – Set a value to be carried over from click to click (during navigation)

$ezr->register_function() – Manipulate results (register a result manipulation function)

$ezr->debug() – Print a screen dump of the main object (and all it's contents)

Internal Functions

$ezr = new ez_results – initialise class

build_navigation() – main function to create nav links

get_num_results() – get total results for query

init_start_row() – make sure start row is set to numeric zero

get_style() – build style=’etc’ or class=’etc’

get_style_na() – build style=’etc’ or class=’etc’ for non active links

merge_num() – merge descriptive text with number insert

RESULT FORMATTING VARIABLES
Basi c Settings
Variable	Sample value	Comment
$ezr->results_prepend	<hr>	Print something before main results (but after browse links)
$ezr->results_open	<table>	Start results (in this case as a table)
$ezr->results_heading	<tr><td>Heading1</td></tr>	Heading row to create column names
$ezr->results_row	<tr><td>COL1</td></tr>	To display the dynamic results use the special symbols COL1, COL2, COL3 etc. (column1, column2, column3 etc).
$ezr->results_row	<tr bgcolor=ALTCOLOR1><td bgcolor=ALTCOLOR2><td bgcolor=ALTCOLOR3>	To display each row with an alternating color. You may use up to three alternating colors. Use the special symbols ALTCOLOR1-3 as shown to the left. To set the colors use the variables $ezr->alt_color1a = "ffffff"; $ezr->alt_color1b = "dddddd"; $ezr->alt_color2a = "ffffff"; $ezr->alt_color2b = "dddddd"; $ezr->alt_color3a = "ffffff"; $ezr->alt_color3b = "dddddd";
$ezr->results_close	</table>	Close the results (in this case table)
$ezr->results_postpend	<hr>	Print something after main results (but before lower browse links)
$ezr->results_empty	No Results	HTML to display if there are no results

NAVIGATION FORMATTING VARIABLES
Navigation – Basic Settings
Variable	Sample value	Comment
$ezr->num_results_per_page	20	DB rows per page
$ezr->num_browse_links	5	i.e. << 1 2 3 4 5 >>
$ezr->nav_top	true	Show nav links at top?
$ezr->nav_bottom	true	Show nav links at bottom?
$ezr->height_below_top_nav	7	In pixels
Navigation – Freeform Variable (Left)
Variable	Sample value	Comment
$ezr->show_mixed_nav_left	true	on/off
$ezr->mixed_nav_left	Browsing CUR_START-CUR_END of TOTAL_RESULTS results (page CUR_PAGE of NUM_PAGES pages)	Browsing 1-5 of 256 results (page 1 of 25 pages) Note 1: You can turn off all other variables and just use this one for ultimate control Note 2: This is displayed on the left hand side of << 1 2 3 4 5 >> Note 3: You must include your own formatting using <span style=’etc’></a> within this variable.
Navigation – Freeform Variable (Right)
Variable	Sample value	Comment
$ezr->show_mixed_nav_right	true	on/off
$ezr->mixed_nav_right	Browsing CUR_START-CUR_END of TOTAL_RESULTS results (page CUR_PAGE of NUM_PAGES pages)	Browsing 1-5 of 256 results (page 1 of 25 pages) Note 1: You can turn off all other variables and just use this one for ultimate control Note 2: This is displayed on the right hand side of << 1 2 3 4 5 >> Note 3: You must include your own formatting using <span style=’etc’></a> within this variable.
Navigation – Count Display
Variable	Sample value	Comment
$ezr->show_count	true	on/off
$ezr->text_count	NUMBER Results	345 Results
$ezr->style_count	font-family: arial; color: 0000FF;
$ezr->class_count	my_class
Navigation – Next
Variable	Sample value	Comment
$ezr->text_next	Next NUMBER >>	Next 20 >>
$ezr->style_next	font-family: arial; color: 0000FF;
$ezr->class_next	my_class
$ezr->style_na_next	font-family: arial; color: 444444;	Not active - grey
$ezr->class_na_next	my_class
Navigation – Back
Variable	Sample value	Comment
$ezr->text_back	<< NUMBER Back	<< 20 Back
$ezr->style_back	font-family: arial; color: 0000FF;
$ezr->class_back	my_class
$ezr->style_na_back	font-family: arial; color: 444444;	Not active - grey
$ezr->class_na_back	my_class
Navigation – Selected Page Number
Variable	Sample value	Comment
$ezr->style_nolink	font-weight: bold; color: 0000FF;	<< 1 2 3 4 5 >>
$ezr->class_nolink	my_class
Navigation – Browse Page Number Links
Variable	Sample value	Comment
$ezr->style_link	font-family: arial; color: 0000FF;	<< 1 2 3 4 5 >>
$ezr->class_link	my_class
Navigation – Number Of Pages Display
Variable	Sample value	Comment
$ezr->show_num_pages	true	on/off
$ezr->text_num_pages	(NUMBER Pages)	(16 Pages)
$ezr->style_num_pages	font-family: arial; color: 0000FF;
$ezr->class_num_pages	my_class
Navigation – Left Hand Seperator
Variable	Sample value	Comment
$ezr->show_sep1	true	on/off
$ezr->text_sep1	-	<< 20 Back - ..
$ezr->style_sep1	font-family: arial; color: 0000FF;
$ezr->class_sep1	my_class
Navigation – Right Hand Seperator
Variable	Sample value	Comment
$ezr->show_sep2	true	on/off
$ezr->text_sep2	-	.. - Next 20 >>
$ezr->style_sep2	font-family: arial; color: 0000FF;
$ezr->class_sep2	my_class
Navigation – Go Back To Start Link
Variable	Sample value	Comment
$ezr->show_start_page	true	on/off
$ezr->text_start_page	[start]	Back to page 1
$ezr->style_start_page	font-family: arial; color: 0000FF;
$ezr->class_start_page	my_class
$ezr->style_na_start_page	font-family: arial; color: 444444;	Not active - grey
$ezr->class_na_start_page	my_class
Navigation – Go To End Link
Variable	Sample value	Comment
$ezr->show_last_page	true	on/off
$ezr->text_last_page	[last of NUMBER pages]	[last of 6 pages]
$ezr->style_last_page	font-family: arial; color: 0000FF;
$ezr->class_last_page	my_class
$ezr->style_na_last_page	font-family: arial; color: 444444;	Not active - grey
$ezr->class_na_last_page	my_class
Navigation – Link mouse-over/hover messages
Variable	Sample value	Comment
$ezr->text_hover_msg_link	Goto page NUMBER of results..	Goto page 10 of results..
$ezr->text_hover_msg_next	Goto next NUMBER results..	Goto next 10 results..
$ezr->text_hover_msg_back	Goto previous NUMBER results..	Goto previous 10 results..
$ezr->text_hover_msg_start	Goto start of results..	Goto start of results..
$ezr->text_hover_msg_end	Goto end of results..	Goto end of results..

VARIABLE REFERENCE
$ezr->set_num_results – Use this variable to set the total number of results manually
Type	$ezr->set_num_results = 0; (INT)
Description	This is to get around a problem where ez_results is not clever enough to deal with complex queries that may have 'select distinct from etc'.. So now the user can now set the number of total result manually.
Usage	$ezr->set_num_results = $db->get_var("some very complex query"); $ezr->query_mysql('SELECT email, login FROM users'); $ezr->display();
$ezr->hide_results – Use this variable to turn off result output
Type	$ezr->set_num_results = true; (Boolean)
Description	If this is set to true then EZ Results will display navigation links only. This is useful if you want to do EVERYTHING outside of EZ Results - but still want to make use of it's excellent PAGINATION FEATURES. I.E. Only print this: << 1 2 3 4 5 >>
Usage	// Your custom query stuff include_once "ez_sql.php"; $results = $db->get_results("some custom query to get this pages results"); include_once "ez_results.php"; $ezr->hide_results = true; $ezr->set_num_results = $db->get_var("some custom query to count TOTAL results"); $ezr->cur_num_results = count($results); // CURRENT num results $ezr->num_results_per_page = 10 $ezr->num_browse_links = 6; print $ezr->get(); // Your custom code to display main results foreach ($results as $result) { print "$result->user $result->name<br>"; } Note: In your custom sql query use the variable $_REQUEST['BRSR'] as the start row.
FUNCTION REFERENCE
$ezr->query_mysql() – Submit query (if using mySQL database)
Arguments	$ezr->query_mysql(query [str])
Description	Submit query (if using mySQL database). Query must be of the type SELECT etc FROM etc.
Usage	$ezr->query_mysql("SELECT login, email FROM users"); $ezr->display();
$ezr->query_oracle() – Submit query (if using Oracle database)
Arguments	$ezr->query_oracle(table name [str], comma separated field list [str], optional where clause [str], optional order by [str])
Description	Submit query (if using Oracle database). Query must be separated into components as shown in usage below. Field list can not contain . I.e. it must be a comma separated list of known* fields.
Usage	$ezr->query_oracle(“my_table”,”id, user, password”,”id > 20”,”id DESC”); $ezr->display();
$ezr->get() – Gets the final output (as returned value)
Arguments	$ezr->get(void)
Description	Gets the final output as returned value (for use with variables and echo)
Usage	$ezr->query_mysql("SELECT login, email FROM users"); echo $ezr->get();
$ezr->display() – Prints the final output to screen
Arguments	$ezr->display(void)
Description	Prints the final output to screen
Usage	$ezr->query_mysql("SELECT login, email FROM users"); $ezr->display();
$ezr->debug() – Prints a screen dump of the main object (and all it’s contents)
Arguments	$ezr->debug(void)
Description	Prints a screen dump of the main object (and all it’s contents). Useful for checking raw HTML code formatting values and raw query results.
Usage	$ezr->debug();
$ezr->set_qs_val() – Set a value to be carried over from click to click (during navigation)
Arguments	$ezr->set_qs_val(variable name [str], variable value [str])
Description	Set a value to be carried over from click to click during navigation. This is useful if you have dynamic options such as ‘sort by’, ‘order by’ etc and would like to remember those values during the navigation process.
Usage	$query = "SELECT login, email FROM users ORDER BY {$_GET[‘order_by’]}"; $ezr->query_mysql($query); $ezr->set_qs_val(“order_by”,”login”); $ezr->display(); Note 1: The above example is shortened for ease of reading but in practise you must make sure that you are not getting unexpected values via GET or POST. I.E. Make sure to test for specific values before allowing a query to take place. Note 2: The above example appends the following to each navigation link. http://yourscript.php?BRSR=0&order_by=login
$ezr->register_function() – Manipulating results. Register a result manipulation function
Arguments	$ezr->register_function(function name [str])
Description	Register a result manipulation function. This is useful if you would like to test and manipulate results after they have been extracted from the database but before they have been displayed. For example you may wish to use an if statement to examine each row of results and decide what to display. Note 1: The function will be called (just before) each time a row is displayed. Note 2: The number of arguments supplied to your function will be based on the number of columns there are in the results. See below for example.
Usage	In order two manipulate results there are a few concepts that must be understood: 1) Results can only be manipulated by new functions that you create. 2) You must register each function using $ezr->register_function() 3) Your function(s) are called just before each row is displayed. 4) Each rows content is dynamically passed to your function(s). 5) Thus allowing you to manipulate each row/column before it is displayed. Before you declare your function you must know how many columns the results will return. For example if the results returned three columns, you would declare your function like so: function my_function($col1,$col2,$col3) { } It does not matter what you call the incoming variables. The important point is that they will always be in the exact same order and amount as specified in your query. Here is a full example of how to manipulate data: function my_data_manipulation($status,$login) { if ( $status == ‘std’ ) { $status = ‘Normal User’; } else if ( $status == ‘admin’ ) { $status = ‘Admin User’; } else { $status = ‘Status Unknown’; } if ( $login == ‘justin’ ) { $status = ‘God.’; } } $ezr->register_function(‘my_data_manipulation’); $ezr->query_mysql("SELECT status, login FROM users”); $ezr->display(); In the above example column1 will be altered from a shortened code into a more descriptive value – then the more descriptive value will be displayed in the result print out (rather than the code that was stored in the database).

EZ Results Help Documentation

Class Features

Quick Example

Introduction

How it works

How Data Is Merged

Formatting Results

Formatting Navigation Links

Manipulating Results

Using EZR Templates

Getting Started

RESULT FORMATTING VARIABLES

Basic Settings

NAVIGATION FORMATTING VARIABLES

Navigation – Freeform Variable (Left)

Navigation – Freeform Variable (Right)

Navigation – Go To End Link

Navigation – Link mouse-over/hover messages

VARIABLE REFERENCE

$ezr->set_num_results – Use this variable to set the total number of results manually

$ezr->hide_results – Use this variable to turn off result output

FUNCTION REFERENCE

$ezr->query_mysql() – Submit query (if using mySQL database)

$ezr->query_oracle() – Submit query (if using Oracle database)

$ezr->get() – Gets the final output (as returned value)

$ezr->display() – Prints the final output to screen

$ezr->debug() – Prints a screen dump of the main object (and all it’s contents)

$ezr->set_qs_val() – Set a value to be carried over from click to click (during navigation)

$ezr->register_function() – Manipulating results. Register a result manipulation function

Basi c Settings