Using csXGraph as a Client Side Control in a Browser.

csXGraph can be used in a browser as a client side control using Javascript (or VBScript). This page contains an explanation of the key points involved in making this work.

The Licence File

csXGraph is a licensed control. It is priced by the number of design time licences required, and that means the number of copies needed of the file csXGraph.lic (csXGraphTrial.lic for the trial version). This licence is needed to run the control in a script based system, such as a web browser but Microsoft have provided us with a system of sharing the licence that is on the web server by creating a Licence Package File (LPK).

We provide a LPK file and it will be copied to the same directory as the OCX file by our installer. This file can be copied to your web server and called using the code shown later. Copying this file to the server makes the web server into a "user" or "seat" and this must be taken into account when deciding which licence type to buy.

You can create the LPK yourself using the Microsoft LPK File Generation Tool (direct download). The OCX file must be registered on the web server and the .lic file must be in the same directory. Running the installation programme for csXGraph will register the control in this way.

The following HTML is used to call up the .lpk file:

<object classid="clsid:5220cb21-c88d-11cf-b347-00aa00a28331">
  <param name="LPKPath" value="csxgraph.lpk">
</object>

If you are using the trial version with the LPK file supplied in our installer, use:

<object classid="clsid:5220cb21-c88d-11cf-b347-00aa00a28331">
  <param name="LPKPath" value="csxgraphtrial.lpk">
</object>

This class ID is used for all .lpk files. The name shown in the VALUE attribute is the name used when creating the .lpk file. It is possible to include the licence information for several OCX controls in the same .lpk file.

*** Important *** The LPKPath attribute value must contain a relative path and must not use a full URL starting with "http://". Presumably this is to prevent LPK files from being called from other web sites, but a full URL will fail even if it points to the same web site. The name of the parameter is "LPKPath" exactly as shown. A common mistake is to copy the value of the parameter here.

Distributing the OCX

The client computer will need a copy of the OCX control in order to run an application using it. For a small number of clients it would be feasible to copy and register the .ocx file onto each machine. This file is csXGraph.ocx (csXGraphTrial.ocx for the trial version). The .ocx file can be distributed royalty free providing the .lic file is not distributed.

The control can be downloaded the first time the client accesses the page that uses it. To do this the .ocx file, or a CAB file containing the .ocx file, must be included in the CODEBASE attribute of the OBJECT tag. We provide a digitally signed CAB file with the full version, but not with the trial version.

*** Important *** The OCX file used to produce the LPK file must be the same version as the file included in the CAB file and if ever the OCX is replaced with a later version a new LPK file must be used.

A CAB file can be produced using any archive software that supports that format, one example is TUGZip.

Calling the Control

The following HTML is used to call up the control. First for the trial version:

<object id="Graph1" classid="clsid:6C14B5B4-8A97-475B-A8D7-55D9275B2C55" codebase="csxgraphtrial.ocx" width="400" height="300"></object>

Then for the full version:

<object id="Graph1" classid="clsid:C68A2D73-03C7-4436-934C-2E42DA50B6E7" codebase="csxgraph.cab" width="400" height="300"></object>

The object name is specified in the ID attribute. This can be any name and it will be used to call properties and methods of the object. If the OCX is included in a .cab file the path to this file will be specified in the CODEBASE attribute. In the examples above we have shown the CODEBASE attribute to use the .ocx file for the trial version and the .cab file for the full versions, because these are the files that we supply. Either format can be used as the codebase but a .cab file is approximately half the size of the .ocx. The width and height attributes can be any value and if they are missing the control will be invisible.

*** Important *** The object tag for the LPK file must be before the object tag for the OCX control.

Changing the Version of csXGraph

If a more recent version of the csXGraph control is used in a web application it is necessary to create a new LPK file using this version. The complete version and build number can be specified in the CODEBASE attribute and this will force the client browser to download the CAB file again if it is using an earlier version. The syntax is:

codebase="csxgraph.cab#version=2,0,0,0"

To find the exact version, right click on the OCX file and select "Properties". Do not right click on the .CAB file or the executable installer because that will not give the version of the OCX.

Example

We have an example showing csXGraph used with Javascript. It is based on the VB example that is shipped with the trial version. This example uses the trial version. The formatting is kept to a minimum to make the code easier to follow.

Example using trial version.

The OCX control is included as an unsigned file so viewing this example will generate a security warning in the browser. This could be avoided for the trial version by installing the trial version of csXGraph. The security aspects of client side OCX controls limit their usefulness. A lot of users are reluctant to download them even if they are signed and they will only run on a Windows platform in Internet Explorer.

Another way of producing web based graphs is to use our server side control, csDrawGraph . This can be used with ASP or Cold Fusion and it generates the graph as an image which can be streamed to the browser.