theCalico.com
 

ReportList - Example Usage

April 2004

Purpose
The ReportList class was originally designed as the foundation to an online reporting system for a database-driven website. It was hoped that it could be used to greatly simplify the migration of a set of database query results to an HTML page, with full user navigation control and export options that would allow power users to analyze data offline, in programs like Excel or OpenOffice Calc. Over the course of several years now the class has lived up to these expectations in numerous projects and has grown to support many more features than I originally imagined. Below is a brief example of some of the more common methods and usages of the ReportList class. A Zipped download of the actual class is available here. Enjoy!

Preface
For the following examples, assume that the $arrData array is set up as the following (more likely your array will have been populated by a database query, but the format will be similar):

$arrData = array();
array_push($arrData, array('strFName'=>'David', 'strLName'=>'Clark',
     'strHomePhone'=>'8012541691', 'strState'=>'ut', 'curAmountPaid'=>123.45));
array_push($arrData, array('strFName'=>'Valerie', 'strLName'=>'Smith',
     'strHomePhone'=>'8019746721', 'strState'=>'in', 'curAmountPaid'=>4914.23));
array_push($arrData, array('strFName'=>'Thomas', 'strLName'=>'Edison',
     'strHomePhone'=>'5191220', 'strState'=>'ut', 'curAmountPaid'=>45.78));
array_push($arrData, array('strFName'=>'Marie', 'strLName'=>'Curie',
     'strHomePhone'=>'8238485', 'strState'=>'ct', 'curAmountPaid'=>798));
array_push($arrData, array('strFName'=>'Isaac', 'strLName'=>'Asimov',
     'strHomePhone'=>'8609784612', 'strState'=>'ct', 'curAmountPaid'=>1540.1));


Example 1 - Instantiation & Output
You have an array of data ($arrData) that you want to output as quickly and easily as possible in a standard HTML table.

require_once('ReportList.php');
$oList = new ReportList();
$oList->makeListFromArray($arrData);

This will output the following table:

Record(s) 1 to 5 of 5 total.
strFName strLName strHomePhone strState curAmountPaid
David Clark 8012541691 ut 123.45
Valerie Smith 8019746721 in 4914.23
Thomas Edison 5191220 ut 45.78
Marie Curie 8238485 ct 798
Isaac Asimov 8609784612 ct 1540.1

 

Example 2 - Specifying Headings
You need to output the HTML table for the $arrData array, but you want to add some title/sub-title information. You'd also like to rename the columns so that they are more appropriate for display - to do this, you must manually specify each column that you want to show. [As before, you must still call the makeListFromArray function to actually output any HTML.]

$oList->setTitle('Customer Search Results');
$oList->setSubTitle('"Amount paid" figures are as of quarter-end.');
$oList->addOutputColumn('strFName', 'First Name');
$oList->addOutputColumn('strLName', 'Last Name');
$oList->addOutputColumn('strHomePhone', 'Home Phone');
$oList->addOutputColumn('strState', 'State');
$oList->addOutputColumn('curAmountPaid', 'Amount Paid');

This will output the following table:

Customer Search Results
"Amount paid" figures are as of quarter-end.
Record(s) 1 to 5 of 5 total.
First Name Last Name Home Phone State Amount Paid
David Clark 8012541691 ut 123.45
Valerie Smith 8019746721 in 4914.23
Thomas Edison 5191220 ut 45.78
Marie Curie 8238485 ct 798
Isaac Asimov 8609784612 ct 1540.1

 

Example 3 - Formatting Data
In our examples so far the "Home Phone" and "Amount Paid" data isn't formatted at all. It would be nice to show these properly as phone numbers, and (U.S.) currency figures. Also, states are normally all upper-case. To do so, modify the calls to the addOutputColumn method to specify data formats for each of these fields. While we're doing that we might as well right-justify the "State" and "Amount Paid" column, since that is more typical of those data formats than left-alignment.

$oList->addOutputColumn('strHomePhone', 'Home Phone', 'phone');
$oList->addOutputColumn('strState', 'State', 'ucase', 'right');
$oList->addOutputColumn('curAmountPaid', 'Amount Paid', 'dollars', 'right');

This will output the following table:

Customer Search Results
"Amount paid" figures are as of quarter-end.
Record(s) 1 to 5 of 5 total.
First Name Last Name Home Phone State Amount Paid
David Clark (801) 254-1691 UT $123.45
Valerie Smith (801) 974-6721 IN $4,914.23
Thomas Edison 519-1220 UT $45.78
Marie Curie 823-8485 CT $798.00
Isaac Asimov (860) 978-4612 CT $1,540.10

 

Example 4 - Pagination of Results
You want to paginate your results so that only a few records show on the page at a time. This can be accomplished with only two extra method calls, assuming you want to use standard $_GET parameters: one to set the pagination target (using allowPaging) and a second to set what record to start outputting data for and how many records to show per page (using setListRange).

$oList->allowPaging(true, 'reportlist_example.html' . '?Base=');
$oList->setListRange($_GET['Base'], 2);

This will output the following table (feel free to try out the pagination links to see how they are constructed, but note that they won't function properly in this static HTML example):

Customer Search Results
"Amount paid" figures are as of quarter-end.
Record(s) 1 to 2 of 5 total.
<< Prev | Back | 1 | 2 | 3 | More | Next >>
First Name Last Name Home Phone State Amount Paid
David Clark (801) 254-1691 UT $123.45
Valerie Smith (801) 974-6721 IN $4,914.23

 

Example 5 - Sorting of Results
You want to allow sorting by any of the columns in your output list, just by clicking on the column header. To do this, you must specify how the data is currently sorted (by what field, and whether or not it is sorted in descending order) and what page should serve as the target to perform the sort (usually just the current page). Two things to note are that the ReportList class will usually sort data properly depending on it's datatype (PHP is not strongly typed, but it is type-aware), and that the normal pagination handling will work in conjunction with the sorting to provide consistent results.

$oList->allowSort(true, $_GET['Sort'], $_GET['SortDescending'], 'reportlist_example.html');

This will output the following table (feel free to try out the sorting links to see how they are constructed, and be sure to hover over them with your mouse for a moment to read the descriptions, but note that they won't function properly in this static HTML example):

Customer Search Results
"Amount paid" figures are as of quarter-end.
Record(s) 1 to 2 of 5 total.
<< Prev | Back | 1 | 2 | 3 | More | Next >>
First Name Last Name Home Phone State Amount Paid
David Clark (801) 254-1691 UT $123.45
Valerie Smith (801) 974-6721 IN $4,914.23

 

Example 6 - Linking by Records
You want each piece of data in the HTML table to be a hyperlink to some other page, possibly with more information about that particular record. This is useful in reporting systems where you want users to be able to drill-down to different levels of detail. You can configure the ReportList class to output static links, or links that are built using data for each individual record as parameters: to accomplish the latter, you must specify the link target page and an array of parameters that you want to use in the link (each parameter must detail the exact data field name and the URL parameter name to use); to accomplish the static links, simply omit the array of parameter information.

$oList->allowLink(true, 'reportlist_example.html',
   array(
     array('name'=>'strHomePhone', 'marker'=>'HP'),
     array('name'=>'strState', 'marker'=>'ST')
   )
);

This will output the following table (feel free to try out the record details links to see how they are constructed, but note that they won't function properly in this static HTML example):

Customer Search Results
"Amount paid" figures are as of quarter-end.
Record(s) 1 to 2 of 5 total.
<< Prev | Back | 1 | 2 | 3 | More | Next >>
First Name Last Name Home Phone State Amount Paid
David Clark (801) 254-1691 UT $123.45
Valerie Smith (801) 974-6721 IN $4,914.23

 

Example 7 - Adding a Touch of Style
Let's say you're not satisfied with the default appearance of the HTML table that the ReportList generates. Certainly a possibility since there's very little formatting applied automatically. Not to fear though, you're not out of luck. The ReportList class provides mechanisms to customize the appearance of all of the following aspects: the overall table, the title, subtitle, recordcount/caption, page navigator row, column heading row, odd & even rows, active rows (i.e. using the mouseover() event) and record links. For instance, if you define the following style classes:

<style>
.resultsMain { background: #cccccc; border: 1px black solid; }
.resultsCaption { background: #cccccc; border: 1px black solid; text-align: left; }
.resultsPaging { background: #999999; font-family: sans-serif; }
.resultsHeading { background: #999999; font-family: sans-serif; }
.resultsRowOdd { background: #cccccc; }
.resultsRowEven { background: #ffffff; }
.resultsRowHover { background: #9999cc; }
.resultsTitle { font-size: 125%; font-weight: 600; }
.resultsSubTitle { font-style: italic; }
.resultsHidden { display: none; padding: 0; margin: 0; }
</style>

You can use the following code to call each class:

$oList->setMainAttributes('class="resultsMain"');
$oList->setTitle('Customer Search Results', '<font class="resultsTitle">', '</font>');
$oList->setSubTitle('"Amount paid" figures are as of quarter-end.',
      '<font class="resultsSubTitle">', '</font>');
$oList->setCaptionAttributes('class="resultsCaption"');
$oList->setPageNavigatorAttributes('class="resultsPaging"');
$oList->setFieldHeadingAttributes('class="resultsHeading"');
$oList->setRowAttributes('class="resultsRowOdd"', 'class="resultsRowEven"', 'resultsRowHover');

Notice that for title & subtitle attributes you must specify both open and closing tags, and for the hover row attributes (the third parameter to the setRowAttributes method) you can specify only a class name - no other attribute specifications will work correctly for the hover mechanism.

The above code will output the following table:

Customer Search Results
"Amount paid" figures are as of quarter-end.
Record(s) 1 to 2 of 5 total.
<< Prev | Back | 1 | 2 | 3 | More | Next >>
First Name Last Name Home Phone State Amount Paid
David Clark (801) 254-1691 UT $123.45
Valerie Smith (801) 974-6721 IN $4,914.23

 

Example 8 - Downloading Lists
The ReportList class provides download functionality in that it can output the headers and stream data back to the client browser to trigger downloads of tab-delimited text files, comma-separated text files, html downloads, and XML data files. With a change of headers, the tab-delimited text files can be seen as native MS Excel files for those of you using MS Office, and the html downloads are easily opened in MS Word or OpenOffice Writer. To utilize this functionality, you simply call the downloadListFromArray method instead of the makeListFromArray that we have been using so far, and pass in the desired download format (the default is the Excel style tab-delimited text). For example, if you were to use the following link on your page:

<a href="reportlist_example.html?Download=1&Type=tab">Download the list as a tab-delimited text file</a>

in your PHP code you would still need to configure the ReportList object identically to what has been shown so far (with the exception that if you call setListRange normally, you should not call it with downloads so that the download is of the entire data set), and then call the appropriate download method:

$oList->downloadListFromArray($arrData, $_GET['Type']);

Examples of the resulting output are as follows:

  • Download the list as a tab-delimited text file (Type=tab)
  • Download the list as a comma separated text file (Type=csv)
  • Download the list as an XML file (Type=xml)

Advanced Usage - Example 1 - Getting ReportList Output Into A String
All of the examples so far have used the makeListFromArray method of the ReportList class to echo the constructed HTML table directly out to the data stream. But what if you're trying to buffer your page output into a variable, or simply need the contents of the HTML table returned as a string variable? Not to worry, because that's exactly how the page you're reading was constructed. The ReportList class provides an alternate method getListFromArray that you can call as in the following:

$sPageBody = $oList->getListFromArray($arrData);


Advanced Usage - Example 2 - Record Link Alt Tags
If you're using the record linking that was explained above in Example 6 extensively, you may find that it would be helpful if you could pop up a small message over each link to try to tell the user where he/she will be going when they click on a link. The anchor element in HTML supports an ALT tag (similar to images) that seems to work fairly well for this purpose. The ReportList class lets you specify this ALT tag for each column, and even do dynamic replacement of real data into the tag that pops up, using the $strLinkDesc parameter of the addOutputColumn method. You could either modify the original column definitions, or add to them, like so:

$oList->setOutputColumnAttribute('strFName', 'linkdesc', 'Click here to view more information about %%strFName%%.');
$oList->setOutputColumnAttribute('strLName', 'linkdesc', 'Want to learn more about %%strFName%% %%strLName%%?');
$oList->setOutputColumnAttribute('curAmountPaid', 'linkdesc', 'Click here to view more information about %%strHomePhone%% in %%strState%%.');

This will output the following table (be sure to hover over the record links):

Customer Search Results
"Amount paid" figures are as of quarter-end.
Record(s) 1 to 2 of 5 total.
<< Prev | Back | 1 | 2 | 3 | More | Next >>
First Name Last Name Home Phone State Amount Paid
David Clark (801) 254-1691 UT $123.45
Valerie Smith (801) 974-6721 IN $4,914.23

 

Advanced Usage - Example 3 - Disabling Record Links For Certain Columns
What if you were using the record linking capabilities of the ReportList class, but for some reason, had a few columns that you didn't want people to drill-down through? The $strFieldLink parameter of the addOutputColumn method is exactly what you need here. This parameter can be used to pass extra information through to the class, to append to the record links constructed for that field. But when set to the flag value of "__NOLINK__" it can also be used to completely disable record linking for a given column. For example:

$oList->addOutputColumn('strHomePhone', 'Home Phone', 'phone', null, null, '__NOLINK__');
$oList->addOutputColumn('strState', 'State', 'ucase', 'right', null, '__NOLINK__');

This will output the following table:

Customer Search Results
"Amount paid" figures are as of quarter-end.
Record(s) 1 to 2 of 5 total.
<< Prev | Back | 1 | 2 | 3 | More | Next >>
First Name Last Name Home Phone State Amount Paid
David Clark (801) 254-1691 UT $123.45
Valerie Smith (801) 974-6721 IN $4,914.23

 

Advanced Usage - Example 4 - Hiding Certain Columns By Default
Sometimes lists, particularly those used for complex reports, end up having a large number of columns. But what if some of those columns aren't necessary all (or even a majority) of the time? In such a case, you might want those extra columns to be available, but hidden when the report first loads. This can be enabled by using an additional CSS class and specifying which columns should be hidden, as in:

$oList->setHiddenColumnClassName('resultsHidden');
$oList->addOutputColumnFromArray(
   array(
     'name'=>'strHomePhone',
     'title'=>'Home Phone',
     'format'=>'phone',
     'fldlink'=>'__NOLINK__',
     'hidden'=>true)
);
$oList->addOutputColumnFromArray(
   array(
     'name'=>'strState',
     'title'=>'State',
     'format'=>'ucase',
     'align'=>'right',
     'fldlink'=>'__NOLINK__',
     'hidden'=>true)
);

This will output the following table:

Customer Search Results
"Amount paid" figures are as of quarter-end.
Record(s) 1 to 2 of 5 total.
<< Prev | Back | 1 | 2 | 3 | More | Next >>
First Name Last Name Home Phone State Amount Paid
David Clark (801) 254-1691 UT $123.45
Valerie Smith (801) 974-6721 IN $4,914.23
Pumpkin the cat with a rubber band
08/03/2014 10:16:39

Valid XHTML 1.0 Transitional