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
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.
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().
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.
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. Example of generated HTML code for StrokeCSIM() 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" /> </map> <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.