Using csXImage as a Client Side Control in a Browser.

csXImage 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

csXImage 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 csXImage.lic (csXImageTrial.lic for the trial version). This licence is needed to run the control in a script based system, such as a web browser but there is 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.

Microsoft produce a tool for creating LPK files (lpk_tool.exe) but it is no longer available as a separate download from their website. The only time that you would need to produce your own LPK file would be if you wanted to use more than one ActiveX control in the same web page and in this situation you would need to find a copy of the LPK file generation tool.

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

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

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 csXImage.ocx (csXImageTrial.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:

Then for the full version:

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 csXImage

If a more recent version of the csXImage 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="csximage.cab#version=5,0,0,3"

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.

Example

We have an example showing csXImage used with Javascript. It is a trivial application allowing shapes and lines to be drawn on an image but it shows how to call up the control and also how to use the mouse events. This example uses the trial version of the control. The formatting is kept to a minimum to make the code easier to follow.

Example using the trial version.

The OCX control is included as an unsigned CAB 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 csXImage. 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.

32 Bit or 64 Bit?

csXImage is now supplied as two OCX files with one being 32 bit and the other 64 bit. At the time of writing this Internet Explorer is a 32 bit application and so it is the 32 bit version of csXImage that should be used. We currently only supply the 32 bit version as a signed CAB file.

Windows 10 and CAB Files

It has come to our attention that when a CAB file is downloaded through Internet Explorer on Windows 10, a warning message is being displayed to indicate that the publisher is unverified, even though the CAB file is signed and the OCX inside it is signed. Once downloaded and installed, the next message asking for permission to use the control correctly identifies the publisher. If the priority is to avoid this warning and verify the publisher on installation, we suggest extracting the OCX from the CAB and pointing the web page to this file, in the codebase attribute of the object tag. The OCX supplied inside the CAB file is digitally signed, but the OCX supplied by the executable installer is not signed.

This appears to be new behaviour and Windows 7 correctly identifies the publisher from the signed OCX inside the signed CAB. This allows the control to be deployed compressed. If we get an update on this behaviour we will modify our instructions accordingly. For csXImage the CAB file is approximately one third the size of the OCX so it is a much smaller download. Once the client has downloaded it, they will use the local copy, so it only needs to be downloaded once.

For more information on using csXImage in clientside Javascript we have a page on tips and troubleshooting and another describing events.

Summary of Javascript related pages.

Another way of working with images in a web application is to use our server side control, csImageFile. This can be used with ASP or Cold Fusion. It does not support mouse events or Twain.

Clientside Javascript examples.
Twain Client Side Example - Scanning an image and uploading to a server.
Client Side Scanning with ADF - Scanning multiple images using an ADF scanner.
Resize and Upload Example - Opening a local image, resizing and uploading to a server.
Client Side Multi-page TIFFs - View edit or scan multi-page TIFF images.