DESCRIPTION
CFX_mapData, and its companion CF_mapKey, can be used to colorize regions on a geographical map under a particular gif format. The trick is that the tag does not modify any pixel in the image, but only the palette of 256 colors contained in the file. It then produces a copy of the gif image, only some colors are changed. By just ajusting a 768 bytes region in the gif file, a completely new image can be generated almost instantly.
Each region on the map should use one distinct, and only one, color from the palette. This way, the tag is able to change the color of all pixels in any region, just by changing the color these pixels use in the palette. This implies that a theoretical maximum of 256 regions can be shown on the map. All colors not used for regions may be used for the rest of the image, like backgrounds and titles. See an example with this map of Canada.
See examples with maps of Canada, France and United States
INSTALLATION
This tag comes in two parts: CFX_mapData is the main tool that creates copies of a gif file according to the data in the supplied query.
CF_mapKey, can be used to generate the color scale, the key to read the map. This tag returns in a query all colors and interval values used to create the map.
In order to use this tag, you first need to take the included mapData.dll; install it on a drive on your server and make it known to the ColdFusion administrator.
You do this by going to the "CFX Tags" tab in the administrator,
- click the "add" button.
- Specify the name as CFX_mapData.
- For the Serverlibrary(dll), specify the path to the dll (the directory into which you copied mapData.dll.
- It should say for "Procedure", "ProcessTagRequest".
The other files are this documentation (mapDataDoc.cfm), and a couple of templates for the examples; just store them in any convenient place in the HTTP area on your development server.
Finally, if you want to run the examples from your server, you need to define a datasourece "mapData" on the Access file mapData.mdb.
SYNTAX
<CFX_mapData MAPFILE = "" QUERY = "" DATACOLUMN = "" COLORCOLUMN = "" MINVALUE = "" STEP = "" NBSTEPS = "" SCALELIST = "" COLORLIST = "" NULLCOLOR = "" OUTFILE = "" > <CF_mapKey MINVALUE = "" STEP = "" NBSTEPS = "" SCALELIST = "" COLORLIST = "" > The attributes for CF_mapKey are the same as for CFX_mapData. Examples |
| TAG | ATTRIBUTE | CONTENT | REQUIRED | DEFAULT |
|---|---|---|---|---|
| <CFX_mapData | MAPFILE= | Full path name of the image file on the server. The file must have an extension GIF and must be a valid GIF image. | Yes | "mapData" |
| QUERY= | Name of the query to be used to read data and colors associated to regions. | Yes | ||
| DATACOLUMN= | Name of the column in the query containing the data to be used to calculate the color. | Yes | ||
| COLORCOLUMN= | Name of the column in the query containing the index in the gif palette associated to each region. This attribute is optional but, if it is not supplied, COLORLIST should be used. | Yes | ||
| MINVALUE= | Minimum value to be considered when calculating colors. | No | 0 | |
| STEP= | Difference between the values in two consecutive color zones. This attribute may be omitted if a scale list is supplied instead. | No | ||
| NBSTEPS= | Number of different data zones to calculate. The first will contain all data between MINVALUE and MINVALUE + STEP, the second between MINVALUE + STEP and MINVALUE + STEP*2, and so on. This attribute may be omitted if a scale list is supplied instead. | No | ||
| SCALELIST= | Comma separated list of scale values. This attribute may be used instead of STEP and NBSTEPS as an alternative way to define how the values range must be subdivided. This way permits non linear scales to be used. | No | ||
| COLORLIST= | Comma separated list of colors. These colors will be used to calculate intermediate colors for each step in the scale of colors by linear interpolation. A minimum of two colors must be given, but more can be given for more accurate and richer scale of colors. | Yes | ||
| NULLCOLOR= | Hexadecimal RGB value of the color to be used for null values in the DATACOLUMN. Most of the time, one will use blank ("FFFFFF"). | No | OUTFILE= | An optional full file name for saving the image on the server. This may be used to save the gif file for further use in case one wants to generate a map for data that will not change in time. | Yes |
HOW TO USE IT
There are especially two kind of situations CFX_mapData could be used:Static but large database
The database from which the data are used to colorize maps is rather static, ie. the values do not change very often, if ever. But the number of types of data and data combinaisons that can be requested implies a hudge number of different maps.Take for instance the maps for the population ratio in the United States. If one want to publish these maps for every year for the last century, it would mean 600 different maps, and it is very unlikely that all of them will ever be requested by visistors. Preparing all of them once for all would be a hudge task. The trick is then to create the map on the fly, as users request them. CFX_mapData is then an ideal solution for this kind of situation.
Dynamic database
On the contrary, one may imagine a situation where a database is updated very often, even every minute, then a map should be recreated every time. Take for instance elections, CFX_mapData could be used to show results by states or by county instantly, as fast as the database is updated during the ballot counting.