Web pages

Using WSpell to check text in Web pages in Internet Explorer

The WSpell ActiveX Spelling Checker control can be used to check the spelling of text entered into forms on Web pages. This document describes how to set up and use WSpell on a Web page accessed by Internet Explorer under Windows 9x/NT.

Using ActiveX controls such as WSpell from desktop development environments like Visual Basic is simple and straightforward. Using ActiveX controls in Web pages is a complex, multi-step process that requires knowledge of Web page scripting, HTML, CAB files, and digital signatures. Internet Explorer is very intolerant of mistakes, and offers little in the way of diagnostic information to help you correct problems. If you are new to using ActiveX controls in Web pages, be prepared for a considerable amount of trial-and-error debugging. See Troubleshooting for some ideas on diagnosing problems.

This document assumes some familiarity with ActiveX controls, with WSpell in particular (see the WSpell Programmer's Guide for information), with the use of ActiveX controls in Web pages (in particular, using licensed ActiveX controls, using the LPK_Tool), with CAB files, and with digital signatures. If you have no experience with these topics, we recommend you consult books and other sources of information. See the Links section for some resources to get you started.

Note that this document assumes the Web page containing WSpell is being viewed by Internet Explorer 3.0 or later. WSpell cannot be used in Netscape Navigator.

Security considerations

Dictionaries used by the WSpell control are stored in local (client side) disk files. These local files are both read and written by WSpell. In addition, WSpell can create new user dictionary files on command.

In the absence of safeguards, a malicious Web page could exploit WSpell's file access to read sensitive information, consume all free space on the local disk drive, or other disruptive actions. (Note that this is true of any ActiveX control which allows named access to local files.) For this reason, WSpell (version 5.11 and later) behaves somewhat differently when it is used in a Web page:

WSpell will open and use only one user dictionary file, named userdic.tlx. The AddUserDictionary and RemoveUserDictionary methods do nothing, The UserDictionaryFiles property cannot be set to anything other than "userdic.tlx".
The CreateUserDictionary method does nothing.
The AddToUserDictionary and DeleteFromUserDictionary methods ignore the file-name parameter, and always add or remove words to and from userdic.tlx. Also, AddToUserDictionary limits the size of the user dictionary to 32,768 words.

All of WSpell's properties and methods were carefully considered, and Wintertree Software is confident that these precautions make WSpell safe to use in Web pages, so it can be marked "safe for scripting" and "safe for initializing." WSpell is marked "safe for scripting" and "safe for initializing" through the IObjectSafety interface, not through the registry.

Starting with version 5.4, the WSpell control is signed with a digital certificate that certifies the control was issued by Wintertree Software and has not been modified since distribution. This assures the browsing client that the WSpell control itself will not inflict damage or steal sensitive information, to the extent that the user trusts Wintertree Software and the certificate issuer.

To use WSpell in a Web page, you may have to place it in a CAB file, which is described below. If you create your own CAB file, it must be digitally signed, and for that you will need your own certificate. Digital certificates may be obtained from Verisign.

Overview

To spell-check text from a Web page using WSpell, the following must be accomplished:

Set up WSpell on the client computer
Create an LPK file to hold WSpell's licensing information
Insert VBScript code in the Web page to spell-check text

Each item is discussed in following sections.

Setting up WSpell on the client computer

Before WSpell can be used, it must be set up correctly on the client computer. Although ActiveX controls contained in Web pages are stored on Web servers, they must be run on the client computer (i.e., the computer running Internet Explorer). WSpell requires access to dictionary files, which must available on the client computer when WSpell is used, either in a known directory or located in the same directory as the wspell.ocx file. If the dictionary files are not located in the same directory as wspell.ocx, WSpell's MainDictionaryFiles and UserDictionaryFiles properties must be set to include the full paths to each dictionary file.

In addition, WSpell must be registered on the client computer.

There are two methods you can use to set up WSpell on the client computer: Using an installation program, and creating a CAB file.

Using an installation program

One way to ensure WSpell and its dictionaries are available on the client computer is to provide a downloadable file with an installer. The downloadable file can be created with commonly available setup generators, such as InstallShield or WISE. The downloadable file is typically a self-extracting executable program, which the user runs on his or her machine. The installer copies and installs WSpell, dictionaries, and required DLLs to the client machine, and registers WSpell and any DLLs which require registering. See "How to redistribute WSpell with your application" in the "Using WSpell" chapter of the WSpell Programmer's Guide for information on dictionaries and DLLs.

If you know WSpell has been installed and registered on each client's computer, you can refer to it in your Web page directly by inserting the following HTML code:

    <OBJECT ID="WSpell1" WIDTH=28 HEIGHT=27
     CLASSID="CLSID:707873c7-03bb-4f1a-95ec-4aaf1c3d463e">
    </OBJECT>

Using a CAB file

The usual way to package WSpell for use on a Web page is to store it in a CAB file. Information on CAB files is available in Microsoft's Cabinet SDK. A CAB file is an archive containing one or more files which are to be installed on the client computer, plus an "INF" file which contains installation instructions. When you refer to a CAB file in a Web page, Internet Explorer will download it from the Web server where it resides and follow the instructions contained within the "INF" file. The CAB file for WSpell would contain wspell.ocx plus any required dictionary files.

The INF file controls the installation of files on the client computer. The following .INF file (named WSPELL.INF) could be used to install WSpell, the American English dictionary, and userdic.tlx:

[version]
    signature="$CHICAGO$"
    AdvancedINF=2.0
[Add.Code]
    wspell.ocx=wspell.ocx
    wspelldlg.hlp=wspelldlg.hlp
    ssceam.tlx=ssceam.tlx
    ssceam2.clx=ssceam2.clx
    userdic.tlx=userdic.tlx
    msvcrt.dll=msvcrt.dll
    mfc42.dll=mfc42.dll
    olepro32.dll=olepro32.dll
[wspell.ocx]
    file-win32-x86=thiscab
    clsid={707873c7-03bb-4f1a-95ec-4aaf1c3d463e}
    FileVersion=5,14,0,0
    RegisterServer=yes
    DestDir=11
[wspelldlg.hlp]
    File=thiscab
    DestDir=11
[ssceam.tlx]
    File=thiscab
    DestDir=11
[ssceam2.clx]
    File=thiscab
    DestDir=11
[userdic.tlx]
    File=thiscab
    DestDir=11
[msvcrt.dll]
    FileVersion=6,0,8168,0
    hook=mfc42installer
[mfc42.dll]
    FileVersion=6,0,8168,0
    hook=mfc42installer
[olepro32.dll]
    FileVersion=5,0,4261,0
    hook=mfc42installer
[mfc42installer]
    file-win32-x86=http://activex.microsoft.com/controls/vc/mfc42.cab
    run=%EXTRACT_DIR%\mfc42.exe

The "DestDir=11" lines in WSPELL.INF tell Internet Explorer to install WSpell in the Windows\System directory. This avoids problems if another application which uses WSpell happens to be installed on the client computer.

The CAB file itself is created using the cabarc utility, which is available as part of Microsoft's Cabinet SDK. The command needed to create a CAB file containing the files listed in the sample .INF file is:

cabarc -s 6144 N wspell.cab wspell.inf wspell.ocx wspelldlg.hlp ssceam.tlx ssceam2.clx userdic.tlx

(The command line above assumes each file exists in the current directory; use full paths if this is not the case.)

The "-s 6144" option reserves space in the CAB file for a digital signature. The CAB file must be signed or it may be rejected by Internet Explorer. A CAB file signed by Wintertree Software, containing the current version of WSpell and the American English dictionary, is included with WSpell. If you want to create your own CAB file, possibly containing other dictionaries, you will have to sign the CAB file using your digital signature. For this you will need your own certificate, available from Verisign.

The CAB file is digitally signed by the SignCode program, which is currently part of Microsoft's CryptoAPI Tools and Authenticode. The following command line is used to sign wspell.cab (newlines have been inserted for clarity):

signcode -spc mycertificate.spc -v myprivatekey.pvk -n "WSpell ActiveX Spelling Checker"
  -i http://www.wintertree-software.com/dev/wspell 
  -t http://timestamp.verisign.com/scripts/timstamp.dll wspell.cab

(Note the spelling of "timstamp.dll".)

Your Web page refers to the CAB file containing WSpell using HTML code similar to the following:

    <OBJECT ID="WSpell1" WIDTH=28 HEIGHT=27
     codebase="wspell.cab#version=5,14,0,0"
     CLASSID="CLSID:707873c7-03bb-4f1a-95ec-4aaf1c3d463e">
    </OBJECT>

Note that the ClassId is WSpell's ClassId.

Creating an LPK file to hold WSpell's licensing information

WSpell is a licensed ActiveX control, which means its implements a special ActiveX protocol that prevents unauthorized use of the control. Before you can use WSpell or any other licensed ActiveX controls on a Web page, you must create an LPK file. The LPK file holds the licensing information for all licensed ActiveX controls on the Web page. LPK files are created using LPK_Tool, which is available from Microsoft. A reference to the "license manager" object must be embedded in the HTML page before any controls that require licensing are embedded. The license manager has no visible representation on the page and refers to the LPK file through a PARAM attribute on its <OBJECT> tag:

    <OBJECT CLASSID="clsid:5220cb21-c88d-11cf-b347-00aa00a28331">
    <PARAM NAME="LPKPath" VALUE="thispage.LPK">
    </OBJECT>

Note that the ClassId is the the ClassId of the license manager, not WSpell.

When you run LPK_Tool, WSpell obtains its licensing information from a file installed on your development computer with the WSpell software development kit. You must recreate the LPK file if WSpell's licensing information changes (if you purchase the commercial version of WSpell after using the evaluation version, for example).

Checking text boxes on Web-page forms

WSpell can be used to check the text contained in text boxes on a Web-page form. The checking might take place in response to a user command, or it might be done prior to submitting the text to a server.

When WSpell detects a misspelled word, the word should be highlighted so the user can see its context. Usually, the highlighting is done by selecting the misspelled word. The approach used to check spelling will depend on the highlighting capabilities of the text box containing the text.

Usually, WSpell will automatically highlight misspelled words in a text box when WSpell's TextControlHWnd property is set. The TextControlHWnd property requires access to the window handle of the text box containing the text being checked. Not all text boxes provide access to their window handles, so different techniques are needed depending on the capabilities of the text box.

Checking text boxes which cannot select text

Simple text boxes, such as those displayed by HTML forms, cannot be instructed to select portions of their text. However, WSpell has a feature which displays the text being checked with highlighting to show misspelled words. This feature is enabled by setting WSpell's ShowContext property to True.

The wspell\ie\examples\CheckTextArea.html file shows how to use WSpell to check the spelling of a standard HTML text area. This example shows a form containing a text area and a button labeled Check Spelling. In the example, WSpell's ShowContext property is set to 1 (True). When the Check Spelling button is pressed, the following steps are performed.

WSpell's Text property is set to the text contained by the text area.
WSpell's Start method is called. WSpell begins looking for spelling errors in the text.
When it encounters a misspelled word, WSpell displays is built-in spelling dialog box (because the ShowDialog property is set to True by default). Because the ShowContext property is True, the dialog box includes a context area which shows the checked text with the misspelled word highlighted.
The user interacts with the dialog box to dispose of the misspelling; possibly by replacing the misspelled word with a correction. If the user corrects the word, WSpell will update the context display and the Text property.
When the Start method returns, the (possibly corrected) text is extracted from WSpell's Text property and replaced in the text area.

Checking text boxes which can select text

Some text boxes can be instructed to select portions of their text, usually through the SelStart and SelLength properties. One such text box is the Microsoft Forms TextBox.

The wspell\ie\examples\CheckTextControl.html file shows how to use WSpell to check the spelling of a selectable text box. This example shows a form containing a Microsoft Forms TextBox and a button labeled Check Spelling. The text box's HideSelection property is set to 0 (False); this allows the selection to remain visible even when WSpell's spelling dialog box has the focus. WSpell's ShowContext property is set to 0 (False), because the text box itself will be used to show context.

At the time of writing, the Microsoft Forms TextBox will not automatically scroll itself to bring the selected text into view, nor does there appear any way to explicitly scroll the text box. As a result, the text box should be sized so that all text will be visible, or use the approach described in "Checking text boxes which cannot select text" instead.

When the Check Spelling button is pressed, the following steps are performed.

WSpell's Text property is set to the text contained by the text box.
Wspell's Start method is called. WSpell begins looking for spelling errors in the text.
If WSpell fires the DoubledWord, WordWithDigits, MixedCaseWord, Capitalization, ConditionallyChangeWord, or MisspelledWord events, the text box's SelStart property is set to WSpell's WordOffset property, and the text boxes's SelLength property is set to the length of WSpell's MisspelledWord property. This selects the misspelled word.
If WSpell fires the ReplaceWord event, the text box's SelStart property is set to WSpell's WordOffset property, and the text box's SelLength property is set to the length of WSpell's MisspelledWord property. This selects the misspelled word. Next, the text box's SelText property is set to WSpell's ReplacementWord property. This replaces the selected text (the misspelled word) with the correction (the replacement word).
If WSpell fires the DeleteWord event, the text box's SelStart property is set to the offset provided as a parameter to the event (the WordOffset property can't be used here for reasons explained in the WSpell Programmer's Guide). The text box's SelLength property is set to the length of WSpell's Misspelled Word property. This selects the word to be deleted. The text box's SelText property is set to an empty string, which deletes the word.
If WSpell fires the UndoChange event, the text box's SelStart property is set to WSpell's UndoOffset property, and the text box's SelLength property is set to the length of WSpell's UndoNewText property. This selects the text inserted by the last change. The text box's SelText property is set to WSpell's UndoOldText property, which replaces the inserted text with the original text.

Troubleshooting

The following may be of some help in diagnosing problems with using WSpell in Internet Explorer.

Make sure Internet Explorer's security level is set to Medium for the "zone" you are using to access WSpell.
Make sure the license manager object is defined before any licensed ActiveX controls on the page.
If you created your own CAB file, make sure the CAB file is digitially signed.
If you code your scripts using JScript rather than VBScript, note that JScript is case-sensitive while VBScript is not.
In some cases Internet Explorer writes an error log to the Temporary Internet Files directory. This file is a text file that may contain diagnostic information that might help you to solve the problem

Links

This section contains links and references to other sources of information on using ActiveX controls in Web pages.

Books:

ActiveX Controls Inside Out, by Adam Denning. Published by Microsoft Press.

Web:

Microsoft reorganizes their Web site frequently, so links from the outside tend to break. However, at the time of writing, the following links were correct. If the links are no longer valid, try searching for the information.

MSDN Online Web Workshop: "...the latest information about Internet technologies, including reference material and in-depth articles on all aspects of Web site design and development."
Packaging ActiveX Controls: "This article introduces a data-compression technology and associated toolset that you can use to package your Microsoft® ActiveX® control for faster, more efficient downloading over the Internet or an intranet."
CryptoAPI Tools Including Authenticode: "This document explains how to digitally sign files, view certificates, and modify certificates with Microsoft® CryptoAPI Tools and Authenticode™ technology."
Microsoft Cabinet SDK: "The Cabinet Software Development Kit provides developers with the components needed to utilize Microsoft's cabinet file technology within other applications, or to build cabinet file management tools."
Licensing ActiveX Controls: "This article explains the licensing strategy for Microsoft® ActiveX® Controls." See also MSKB article Q159923.

	WSpell ActiveX Spelling Checker

Home Site index Contact us Catalog Shopping Cart Products Support Search
You are here: Home > Products > Developer tools > WSpell > Web pages

WSpell ActiveX Spelling Checker Home Site index Contact us Catalog Shopping Cart Products Support Search You are here: Home > Products > Developer tools > WSpell > Web pages