CF_PageThru v1.0.1 Tag Documentation

CF_PageThru v1.0.2 Tag Documentation

tag written by Roy P. Johnston, Jr.
Created June 4, 1999 - Updated Friday, February 28, 2003

The most current version of this document is available at: http://www.johnstons.org/wdc/pub/cfusion/customtags/CF_PageThru/CF_PageThru.html

Description
Attributes
Returned Values
Error Values
Syntax
Sample Code
Hints & Tips
Package Information & Download
Support
Version History

Description

CF_PageThru aids in creating page-through navigation similar to what is found on search engines. This is nice for breaking up large query results onto multiple pages. CF_PageThru will calculate the first and last rows to be displayed on the current page of query output. In addition, CF_PageThru will create a navigational bar to page-through a multi-page query output. Sample navigation looks like:

Page 3 4 5 6 7

The red arrows are the Next Page/Previous Page buttons. The double red arrows are the Next Page Group/Previous Page Group buttons. A page group is a full or partial set of all pages. The number of pages displayed in a page group is determined by the PAGEGROUP attribute.

Attributes

Attribute	Type	Description
TOTALRECORDS="integer"	Required	Specifies the records returned (QueryName.RecordCount) by the query to be paged-through.
CURRENTPAGE="integer"	Required	The current page in the query that is to be displayed.
TEMPLATEURL="URL Path"	Required	The URL path of the template that is paging though the query. This will usually be that same template that is calling CF_PageThru. You can use the CGI variable `SCRIPT_NAME` to specify the URL of the calling template.
ADDEDPATH="string"	Optional	Additional URL parameters that will tacked on to the URLs of the navigation. The parameter list must start with an ampersand (&).
DISPLAYCOUNT="integer"	Optional	Specifies the maximum number of records to be displayed per page. The default is 25 records.
PAGEGROUP="integer"	Optional	The maximum number of numeric page links to be displayed at one time in the page-through navigation. Set PAGEGROUP="0" to turn page grouping off. The default is 10 pages.
IMAGEPATH="URL Path"	Optional	the URL path of the images to be used in the navigation. This includes buttons for Next/Previous and Next Group/Previous Group. The default is "" (empty path) which results in using the URL directory of the current template for images. Set IMAGEPATH="NONE" to use hypertext buttons.
IMAGEHEIGHT="integer"	Optional	The height of all image buttons. The default is 10 pixels.
IMAGEWIDTH="integer"	Optional	The width of all image buttons. The default is 10 pixels.
HILITECOLOR="hex code or color literal"	Optional	The text color of the current highlighted page number in the page-through navigation. The default is "Red".
PREVIOUSSTR="string"	Optional	The hyperlink text of the previous button. The default is "<".
NEXTSTR="string"	Optional	The hyperlink text of the next button. The default is ">".
PREVIOUSGROUPSTR="string"	Optional	The hyperlink text of the previous group button. The default is "<<".
NEXTGROUPSTR="string"	Optional	The hyperlink text of the next group button. The default is ">>".

Returned Values

Variable	Description
PT_StartRow	The first row of the query to be displayed on the current page.
PT_EndRow	The last row of the query to be displayed on the current page.
PT_PageThru	Page-through navigation. Output this variable wherever you want the page-through navigation to be displayed.
PT_ErrorCode	Numeric error code that corresponds with the descriptive `PT_ErrorMessage`.
PT_ErrorMessage	Error message

Error Values

Code	Message
0      	OK.
1	The 'TotalRecords' parameter must be a positive integer.
2	The 'DisplayCount' parameter must be an integer greater than zero.
3	The 'PageGroup' parameter must be a positive integer.
3	The 'CurrentPage' parameter must be an integer greater than zero.

Syntax

Simple Form:

<CF_PAGETHRU TOTALRECORDS="#MyQuery.RecordCount#" CURRENTPAGE="#CurrentPage#" TEMPLATEURL="#SCRIPT_NAME#">

Advanced Form:

<CF_PAGETHRU TOTALRECORDS="#MyQuery.RecordCount#"
	CURRENTPAGE="#CurrentPage#"
	TEMPLATEURL="#SCRIPT_NAME#"
	ADDEDPATH="&SearchCategory=Computers"
	DISPLAYCOUNT="50"
	PAGEGROUP="15"
	IMAGEPATH="/images/"
	IMAGEHEIGHT="15" IMAGEWIDTH="25"
	HILIGHTCOLOR="##00FF00">

<CF_PAGETHRU TOTALRECORDS="#MyQuery.RecordCount#"
	CURRENTPAGE="#CurrentPage#"
	TEMPLATEURL="#SCRIPT_NAME#"
	ADDEDPATH="&SearchCategory=Computers"
	DISPLAYCOUNT="50"
	PAGEGROUP="15"
	IMAGEPATH="NONE"
	HILIGHTCOLOR="##00FF00"
	PREVIOUSSTR="[prev]" NEXTSTR="[next]"
	PREVIOUSGROUPSTR="[rew]" NEXTGROUPSTR="[ff]">

Sample Code

Sample code and output for CF_PageThru.

Hints & Tips

If only one pageful of results is returned by a query, PT_PageThru will return an empty string.
You can set the TEMPLATEURL attribute equal to the CGI variable SCRIPT_NAME to specify the URL of the calling template (See Syntax).
CF_PageThru is defaulted to use the graphic images packaged with the CF_PageThru. Copy the graphic images into the directory of the calling template.
Set the PAGEGROUP attribute to 0 (zero) to turn off page grouping. This will have the effect of displaying all pages for a query in the navigation, even if there are 1000 pages.
Be sure to set IMAGEPATH="NONE" when using hypertext buttons for Previous/Next and Previous Group/Next Group.
Use the <CFPARAM> to default CurrentPage to 1 (one) in th calling template.
Use the ADDEDPATH attribute to pass through any parameters needed for the query. ADDEDPATH can also be used to pass sorting parameters.

Package Information & Download

Files: PageThru.cfm, CF_PageThru.html, CF_PageThru-sample.html, left.gif, right.gif, lleft.gif, rright.gif
Download: CF_PageThru.zip
An unencrypted version of this tag is available at: http://www.johnstons.org/wdc/pub/cfusion/dltag.cfm

Support

Tech support can be obtained at: http://www.johnstons.org/wdc/pub/cfusion/support.cfm.

Send suggestions or comments to ihuj@yahoo.com. Submit bug reports or code modifications to ihuj@yahoo.com with the subject line "CF_PageThru".

Version History

1.0.2
Released December 9, 2002 - Features: Minor bug fix allowable range for CurrentPage.

1.0.1
Released 9/16/99 - Features: Minor bug fix in returned error messages.

1.0
Released 6/4/99 - Features:

Calculates the first and last rows to be displayed in a page of a multi-page query output.
Creates a navigation bar to page-through a multi-page query output.