(See Chapter 10. Using CSIM (Client side image maps) for a full description on the usage of CSIM together with the library)

You can also use the cache system for images that uses image maps (CSIM) as well. The cache system interface is slightly different in this case since the cache needs to store both the cached image and the cached image-map. It also needs to change due to the added complexity with CSIM scripts not sending back an image but rather a pre-formatted HTML page. The two major differences from the non-CSIM cache is:

To use the cache with CSIM you have to call the Graph::CheckCSIMCache(). As with the caching for non-CSIM you have to supply a name to be used for the cached version (it can be manually or automatic) as well as an optional timeout value. The default timeout value if nothing else is specified is 60 minutes.

The name argument requires some more explanations. The file name must be specified as a relative name.

For example "myimage" or perhaps "firstpage/image3".

The reason for his is that a script that uses CSIM does not send back an image. Instad it sends back a HTML page which includes the image map coordinates and has an included "<img href=" ... ">" tag which references the image script recursively in normal cases but if the image is found in the cache this reference will be to a static image instead.

Depending on the installation of the library this will now end up in the directory specified in the CSIMCACHE_DIR define. This must also be a directory accessible by the normal HTTP/PHP process. By default, if nothing else is specified, a directory called "csimcache" will be created in the same directory as the image script itself.

The default value has the drawback that the directory from where the script is executed must also be writable by the process running PHP. Best practice here is to keep the number of writable directory for PHP down to a minimum and re-use the same directory as is used for the standard cache.

This however, requires that the PHP and HTTP setup is such that the cache directory is also accessible by the HTTP server from the htdocs root.

The CheckCSIMCache() method checks the cache for an existing cached version and if found it returns it and halts execution of the script. So, this call should be the first call after the creation of the core graph instance, i.e. $graph = Graph($width,$height) and before any heavy work is done to create the image so that no unnecessary work is done in case a cached image + image map is found.

The general structure of a script that uses CSIM and cache should follow the template shown in

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<?php
require_once( 'jpgraph.php');
 
// ... any necessary includes
 
$width = ...
$height = ...
$graph = new Graph($width,$height);
 
// Check cache and use a 10 min timeout
$graph->CheckCSIMCache('csim_image1',10);
 
// If a cached version exists, execution halts here
// and the cached HTML image map is sent back
 
// ... construct and format the graph
 
// ... finally send back the image map HTML script
$graph->StrokeCSIM();
?>

Please note that it is not necessary to pass any argument to the final call of StrokeCSIM()