Custom Tag: cf_randomquery
Version: 1.0
(c) 2004, Rizal Firmansyah, rizal.firmansyah@masrizal.com

Disclaimer:
This custom tag was written to help developers create a random recordset easily, 
and without the need to know or change their SQL code.

This custom tag comes with a very low price.
I believe the price of this custom tag is less than an average 1 hour programmers rate.
But by using this custom tag, you save lots of your valuable time writing SQL code to produce the same result.
And because of its very low price (esp. comparing your rate to create such a function in SQL),
i would like to give a license to use this tag is for "1 copy per developer".
That means each developer must purchase a copy of this custom tag for his/her own use.

For full license and disclaimer about this tag, please read: license.txt
-------------------------------------------------------------------------------

cf_randomquery is a quick solution to give a random recordset.
This custom tag supports any kind of query (recordset) as the datasource, not limited to specific database.

*** Requirements: 
ColdFusion 5, MX and up

*** Usage:
<cf_randomquery DataSource="query/recordset source - mandatory" 
								Name="The name query. The query name is used later in the page to reference the query's record set - mandatory" 
								MaxRows="Specifies the maximum number of rows to return in the record set - optional (default all rows)">

*** Examples:
1. Randomize recordset from database query.
<!--- query database for information --->
<cfquery name = "GetParks" dataSource = "cfsnippets">
SELECT   PARKNAME, REGION, STATE
FROM     Parks 
</cfquery>
<cf_randomquery DataSource="GetParks" Name="RandomParks"> <!--- RandomParks will contain all rows from GetParks in random order --->
<cf_randomquery DataSource="GetParks" Name="RandomPark" MaxRows="1"> <!--- RandomPark will contain 1 random row from GetParks --->

2. Randomize recordset from programmatically created query
<cfset myQuery = QueryNew("name, address, phone")>
<cfset newRow  = QueryAddRow(MyQuery, 2)>
<cfset temp = QuerySetCell(myQuery, "name", "Fred", 1)>
<cfset temp = QuerySetCell(myQuery, "address", "9 Any Lane", 1)>
<cfset temp = QuerySetCell(myQuery, "phone", "555-1212", 1)>
<cfset temp = QuerySetCell(myQuery, "name", "Jane", 2)>
<cfset temp = QuerySetCell(myQuery, "address", "14 My Street", 2)>
<cfset temp = QuerySetCell(myQuery, "phone", "588-1444", 2)>
<cf_randomquery DataSource="myQuery" Name="RandomMyQuery"> <!--- RandomMyQuery will contain all rows from myQuery in random order --->
<cf_randomquery DataSource="myQuery" Name="RandomMyQuery1" MaxRows="1"> <!--- RandomMyQuery1 will contain 1 random row from myQuery --->

*** Important Note:
This custom tag adds one column name "cf_randomquery" to the resulting recordset.
You may want to remove this column if your application manipulate data from query directly without specifying column name.
So, please keep in mind that you are recommended to specify column names to manipulate data from resulting random query.

-------------------------------------------------------------------------------

Hope you find this tag useful.

Sincerely,
Rizal Firmansyah
<rizal.firmansyah@masrizal.com>