10.4. Using StrokeCSIM()

The simplest way of creating a creating a CSIM image is with the StrokeCSIM() method. As mentioned before this method actually returns a (small) HTML page containing both the image-tag as well as the image map specification. Hence it is not possible to use a script that ends with this method in a standard image-tags src property.

There are two ways to create CSIM (or get hold of) the image maps

  1. Use the CSIM image script as the target in a standard anchor reference, for example

    <a href="mycsimscript.html"> 

    This has the drawback that the image page will only contain the image and nothing else.

  2. The other way will allow the image script to be included in an arbitrary HTML page by just including the image script at the wanted place in the HTML page using any of the standard "include" php statement. For example

    <h2> This is an CSIM image </h2>
    <?php include "mycsimscript.php" ?>

Note: If there are several CSIM images on the same page it is necessary to use "include_once" in the scripts for the inclusion of "jpgraph.php" and the other jpgraph library files since the files will be included multiple times on the same page and one or more "Already defined error" will be displayed.

The process to replace Stroke() with StrokeCSIM() is strait forward. Replace all existing calls to Stroke() with the equivalent calls to StrokeCSIM().

10.4.1. Optional argument to StrokeCSIM()

Once difference compared with Stroke() is that if a filename is supplied to the StrokeCSIM() method it does not specify a file to write an image to as is the case with Stroke(). The signature for the method is

StrokeCSIM($aScriptName='auto', $aCSIMName='', $aBorder=0)

The first (optional) argument is the name of the actual image script file including the extension. So for example if the image script is called "mycsimscript.php" the call should be

 $graph -> StrokeCSIM ( 'mycsimscript.php' ) 

By using the predefined name 'auto'. This will be done automatically.


Why does the script name need to be used as the first parameter? The reason is that in the creation of the HTML page which is sent back we need to refer to the script in the image tag. In older versions of PHP there where no 100% way of getting hold of the actual script name in all circumstances and it was then necessary to specify it here. In PHP5 (and newer version of PHP4) this is no longer a problem but this parameter is still kept for backward compatibility.

The other arguments to StrokeCSIM() are optional as well. The second argument specifies the id that connect the map with the corresponding image. Please note that if several CSIM images are used in the same HTML page it is necessary to specify the image map name as the second parameter since all image maps must be unique to properly match each image map against each image. Please consult the class reference StrokeCSIM() for more details.

The final argument specifies whether the image should have border or not.

10.4.2. How does StrokeCSIM() work?

Knowledge of the exact technical details of the way StrokeCSIM() works is probably not needed by many people but for completeness we outline those details in this short section.

The fundamental issue we have to solve is that we must be able to call the image script in two modes. When the user includes the image script the StrokeCSIM() method should return the HTML page but when the image script is later called directly in the image tag it must not return an HTML page but rather the actual image.

The way this is solved is by using one GET argument which is passed on automatically when we use the image script name in the <img>-tag.

A look at the generated HTML from StrokeCSIM() will make this clear. In Figure 10.1 the resulting HTML code after running the example script bar_csimex1.php is shown. The argument to the src-property of the image tag is not simply the script name but the script name with a additional argument, ?_jpg_csimd=1. This argument is passed on to the library which then will run the script again but this time only generate the image and not the HTML. (In the JpGraph internal code this pre-defined argument is checked for and if it exists the image is send back and not the HTML page.)


The actual string name of this parameter is defined by a DEFINE statement in JpGraph, _CSIM_DISPLAY.

Figure 10.1. Example of generated HTML code for StrokeCSIM()

<map name="__mapname1828__" id="__mapname1828__" >
<area shape="poly" coords="74, 210, 74, 165, 92, 165, 92, 210"  href="bar_clsmex1.php#1" title="val=12" alt="val=12"  />
<area shape="poly" coords="118, 210, 118, 112, 136, 112, 136, 210"  href="bar_clsmex1.php#2" title="val=26" alt="val=26"  />
<area shape="poly" coords="162, 210, 162, 176, 180, 176, 180, 210"  href="bar_clsmex1.php#3" title="val=9" alt="val=9"  />
<area shape="poly" coords="206, 210, 206, 146, 224, 146, 224, 210"  href="bar_clsmex1.php#4" title="val=17" alt="val=17"  />
<area shape="poly" coords="250, 210, 250, 93, 268, 93, 268, 210"  href="bar_clsmex1.php#5" title="val=31" alt="val=31"  />
<img src="bar_csimex1.php?_jpg_csimd=1" ismap="ismap" usemap="#__mapname1828__" border="0" width="310" height="250" alt="" />


As the astute reader has come to realize CSIM scripts has a performance impact in that each script has to be run twice. Once to get hold of all the coordinates and generate the image and a second time via the <img> tag in generated HTML. The library is intelligent enough to minimize the code to run so that it only runs what is absolutely necessary. This means that roughly 75% has to be run which yields a total overhead of around 1.75 times when generating a CSIM image.

10.4.3. Image maps and the cache system

For version 1.9 and later the cache system has been extended to include the CSIM maps as well. For each CSIM graph two files are stored in the cache, the image file itself as well as the wrapper HTML with the actual image map.