Research It Developer's Guide

This document is intended for script developers and software developers. It provides information necessary to create custom rule sets and lookup modules for Research It. Before you begin, you should be familiar with JAWS, XQuery, XPath, XML, and HTML.

A comprehensive book on XQuery is available from Bookshare (for Bookshare subscribers) at:

For basic tutorials about XQuery, XPath, XML, and HTML, refer to:

http://www.w3schools.com.
These tutorials provide an overview, while the book covers XQuery comprehensively.

Research It is a JAWS tool that uses queries written in XQuery to manipulate XML databases and other data sources. Using the information outlined in this document, you can create a basic query by making your own rule set files to use with the supplied Freedom Scientific lookup module DLL, or you can create your own lookup module DLL to support and perform customized research operations.

Use the following links to move to a topic of interest:

What is Research It?
Definitions
Creating a Rule Set
Testing a Rule Set with JAWS
Lookup Module API
Built-in Script API
Script Wrapper Functions

What is Research It?

Features such as Web Slices in Internet Explorer 8 and gadgets saved to your desktop or Windows Sidebar are intended to make it easy for you to quickly obtain information. This material is presented in a format that is quick to scan visually. However, when using assistive technology tools, there is often extra information presented that is easier to ignore visually than when listening or reading with braille.

Research It is a JAWS feature that provides quick access to information while also making it easy to return to your primary task. Use just a few keystrokes to look up information and display salient data in the Virtual Viewer. When you have finished researching, press another keystroke to return to the task you were performing before the research started.

Definitions

Lookup Module: A dynamic link library (dll) that encapsulates a particular lookup technology that can support one or more lookup sources. For example, LiveResourceLookup.dll is the generic lookup module distributed with JAWS.
Lookup Source: The XML database or data source that is queried. Some of the lookup sources provided with JAWS are Major League Baseball scores, National Football League scores, Top News Stories, Wikipedia, and Wiktionary. These items are visible to a JAWS user when he or she opens the Research It dialog box.
LiveResourceLookup.dll: The Freedom Scientific lookup module. It resides in the LookupModules subdirectory of the JAWS program directory. This DLL can support multiple lookup sources: those created by Freedom Scientific and supplied with JAWS, and those created by third-party developers who want to create their own queries.
Lookup Module Raw Name: The name of a lookup module DLL, if one has been implemented and it has no rule sets associated with it (for example, MyLookup.dll), or the name of a rule set file (for example, LRL_Wiki) if the module uses them.
Lookup Module Friendly Name: The localized name of a lookup module. This name is used in the Configuration Manager as well as the Lookup Module selection dialog which is displayed by the scripts. For a custom DLL, the developer can specify this information inside the DLL. For a rule set, this is the value from the RUL file.
Rule Set: A rule set is a set of instructions that allow users to quickly and easily specify how to access information from a lookup source. Users can create rule sets for new lookup sources and use them with Freedom Scientific’s generic lookup module and scripts. A rule set consists of an RUL file, which specifies the friendly name, description, and other configuration information, and a QRY file, which contains the XQuery used to query the lookup source.
Primary Lookup Source: This is the default lookup source as set in Configuration Manager by a JAWS user.
Research It: A JAWS feature that uses queries written in XQuery to search XML databases and other data sources. A developer creates a rule set to perform the search. When implemented, a JAWS user can launch Research It using a variety of JAWS keystrokes. When initiated, the feature uses the selected lookup resource, as defined by a rule set, to display data in the JAWS Virtual Viewer window. After reading or copying the data, the user closes the Virtual Viewer and returns to his or her previous cursor location prior to launching the search.
XQilla: An open source implementation of XQuery. Developers who are creating Research It rule sets can use XQilla functions in their queries. These functions are documented at http://xqilla.sourceforge.net/ExtensionFunctions.
Rule File: A rule file is a file with the RUL extension. The rule file contains general configuration information for a rule set.
Query File: A query file is a file with the QRY extension. The query file contains the XQuery used to gather information from the lookup source.
JAWS Key: The primary modifier key used with JAWS keystrokes. In the Desktop keyboard layout, the INSERT key is used by default. In the Laptop keyboard layout, the CAPS LOCK key is used by default.
JAWS Key+WINDOWS Key+R: The JAWS keystroke that launches Research It. The primary lookup source is used.
JAWS Key+CTRL+WINDOWS Key+R: The JAWS keystroke that launches Research It from anywhere using the JAWS primary lookup source.
JAWS Key+F2: The JAWS keystroke that opens the JAWS Manager dialog box. You can then select Research It from the available list of managers to run the Research It feature, or you can select Configuration Manager from the list to set the Research It options for a specific application.

Creating a Custom Rule Set

At its core, Research It consists of a lookup module and a rule set. The Freedom Scientific lookup module, LiveResourceLookup.dll, supports user-defined rule sets. A rule set consists of a query and a variety of settings that specify how the rule set is exposed to the end user and how the query is executed.

To create a custom rule set, you must provide two files: a rule file, which uses the .rul file name extension, and a query file, which uses the .qry file name extension. Both files must use the same base name, for example, Wiktionary.rul and Wiktionary.qry. For additional information, see File Name and File Folder Location.

Use a text editor to create the rule and query files.

Rule File (.rul)

The rule file uses an INI file format and contains one section, [Details]. Use the following keys in this section:

Key Name	Value
FriendlyName	A string specifying a “friendly” name for the rule set. Mandatory. Maximum 100 characters. This is the text that appears in the lookup source list when a JAWS user opens the Research It dialog box.
Description	A string containing a brief description for the rule set. Optional. Maximum 500 characters. This is the information that appears when a JAWS user selects the Description button in the Research It dialog box in JAWS Configuration manager.
Timeout	An unsigned integer containing the timeout in milliseconds to be used for queries. Any query using this rule set will be aborted if it exceeds the timeout specified. The default timeout is 15000 milliseconds. This value is used if no timeout value is specified. A longer timeout may be required if the Web site that is queried is slow, or a large amount of data is returned, or if the query is complicated.

Rule File Example

The following is an example of a valid RUL file:

[Details]
FriendlyName=Wikipedia
Description= Use Wikipedia.com to look up and display the encyclopedia entry for a word or phrase.
Timeout=15000

Query File (.qry)

The query file uses XQuery to retrieve a specific resource (for example, a Wikipedia page), parse the results, and then return output as a single string. A number of additional XQilla and XSLT functions are available for use within the query file. The XQilla implementation of XQuery lets you parse an HTML page as an XML document. For additional details and information, refer to http://xqilla.sourceforge.net/ExtensionFunctions.

The method to get the HTML document as an XML document node is:

declare variable $doc := xqilla:parse-html(unparsed-text($URL));

where $URL is the full URL path string.

Search Token

Within a query file, you can use the token |ARG_1...ARG_n| to mark a location where input is substituted into the query string. It is not necessary to place the token directly into a search URL. You can place a token into a variable that can be further parsed or modified prior to its use. This lets you pass multiple arguments into |ARG_1...ARG_n| and parse them into separate variables within the query code.

Query File Example

The following is an example of a valid query:

declare namespace wiki = "http://opensearch.org/searchsuggest2";
declare variable $new_line := '
';
declare variable $doc := doc("http://en.wikipedia.org/w/api.php?action=opensearch&search=|ARG_1...ARG_n|&format=xml");
for $item in $doc/wiki:SearchSuggestion//wiki:Item[1]
return (fn:normalize-space(data($item//wiki:Description)), $new_line)

In this query, the |ARG_1...ARG_n| token will be replaced by the search term that is passed down from the JAWS script.

Function Library for Query Tasks

Freedom Scientific has a function library to aid you in performing common query tasks. Import the library in your query using an import statement:

import module namespace fsi = "http://freedomscientific.com/ResearchItImports" at "ResearchItLibrary.jri";

You can then use functions and variables from the ResearchItLibrary in your own scripts; just prefix those calls with the namespace you chose (fsi, in the previous example). For example, the ResearchItLibrary function "output-clean-lines" allows you to easily output a sequence of nodes as plain text, separated by new lines, with whitespace normalized:

fsi:output-clean-lines($yourNodesHere)

The ResearchItLibrary.jri file is located in the LookupModules subfolder of the JAWS folder. For example: C:\Program Files\Freedom Scientific\JAWS\<version number>\LookupModules.

Use a text editor to open and read the file.

File Name and File Folder Location

When naming and saving rule set files, do the following:

Use the .rul file name extension for the RUL file.
Use the .qry file name extension for the QRY file.
Use the same base name for both the RUL and QRY files, for example, Wiktionary.rul and Wiktionary.qry.
Save both RUL and QRY files to the same RuleSets folder.

For example, in Windows 7 and Windows Vista, save rule set files to the following user location:

C:\Users\<user name>\AppData\Roaming\Freedom Scientific\JAWS\<version number>\SETTINGS\enu\RuleSets\<file name.rul> and <file name.qry>

In Windows XP, save rule set files to the following user location:

C:\Documents and Settings\<user name>\Application Data\Freedom Scientific\JAWS\<version number>\SETTINGS\enu\RuleSets\<file name.rul> and <file name.qry>

Note: Shared rule sets, such as the Freedom Scientific rule sets provided with JAWS, are saved to the following location in Windows 7 and Windows Vista:

C:\ProgramData\Freedom Scientific\JAWS\<version number>\Settings\enu\RuleSets\<file name.rul> and <file name.qry>

In Windows XP, shared rule sets are saved to:

C:\Documents and Settings\All Users.Windows\Application Data\Freedom Scientific\JAWS\<version number>\SETTINGS\enu\RuleSets\<file name.rul> and <file name.qry>

Shortcut to JAWS User and Shared Locations

When JAWS is installed, you can quickly access user and shared folder locations using the Explore JAWS submenu. To use this shortcut, do the following:

Press WINDOWS Key to open the Start menu.
Select All Programs and then press RIGHT ARROW.
Press J to navigate to the correct JAWS submenu version (for example, JAWS 11.0), and then press RIGHT ARROW to open the JAWS program group. The Explore JAWS submenu is the first item.
Press RIGHT ARROW and then do one of the following:

To access user folders, select Explore My Settings and press ENTER.
To access shared folders, select Explore Shared Settings and press ENTER.

Finally, select and open the RuleSets folder.

Testing a Rule Set with JAWS

After creating the rule set files, and copying the files to the appropriate user location on your computer, you can run a quick test using JAWS and JAWS scripts to verify if your lookup source works.

Note: When you initially create a rule set, you must perform a one-time task that makes it available to JAWS. This procedure is described in Making a Rule Set Discoverable.

Note: When using JAWS with a desktop computer, INSERT is the JAWS Key. When using JAWS with a laptop computer, CAPS LOCK is the JAWS Key.

Launch JAWS.
Do one of the following to turn on Script Utility Mode:

On a desktop computer, press JAWS Key+WINDOWS Key+NUM PAD MINUS.
On a laptop computer, press JAWS Key+WINDOWS Key+DASH.

Press JAWS Key+WINDOWS Key+D to launch the Select Rule Set to Debug dialog box. A list that contains all rule sets appears.
Press UP or DOWN ARROW to navigate to your rule set, and then press ENTER. The Apply Search Term to Debug dialog box opens.
Type one or more words into the edit field and press ENTER.
The Virtual Viewer window opens and displays an error code. If the rule set is successful, the error code is 0 and feedback, based on your query, appears. If the rule set fails, use the error code and feedback to help you troubleshoot your rule set files.

Note: Errors generated using XQilla for XQuery result in Error code 3, and output a resulting XQuery error string usually containing a line number for you to trace.

Note: When running this debug, any hyperlinks you generate in your query are not presented as links in the Virtual Viewer. Instead, it outputs the raw HTML source. The user script functions for Research It create the hyperlinks using the JAWS Script callback methods and use the function UserBufferAddTextWithHtml to do it.

Making a Rule Set Discoverable

The following describes how to use the JAWS Configuration Manager (JCF) to make your rule set visible to JAWS while running the debugger as described earlier.

With JAWS running, press JAWS Key+F2 to open the Run JAWS Manager dialog box.
Press C to navigate to Configuration Manager in the list and then press ENTER.
Press ALT+S and then R to open the Research It Options dialog box.
It contains a list box showing all lookup source items (rule sets) currently available to JAWS. Each item in the list has a check box. When an item’s check box is clear, it will not appear in the lookup list for the current JCF file.
Press UP or DOWN ARROW to select your rule set, and then press SPACEBAR to select the check box.
Select OK to save changes and close the Research It Options dialog box.
Press ALT+F followed by S to save Configuration Manager changes, and then ALT+F4 to close Configuration Manager.

Lookup Module API

If you are interacting with a lookup source that does not support XQuery, or you must protect proprietary data, or your lookup source requires user authentication, then you must create your own DLL API. The following describes the API methods that your lookup module must support. Provide this information to your DLL API developer.

Initialize

Syntax

HRESULT Initialize(void);
Your implementation of Initialize should perform any initialization necessary for the lookup module. Any initialization that must not be performed in DllMain (thread creation, synchronization, etc.) should be performed here. JAWS call Initialize prior to calling any other lookup module functions.

Return Value
Return S_OK (0x00000000L) if initialization is successful, otherwise E_FAIL (0x80004005L).

DeInitialize

Syntax

HRESULT DeInitialize(void);
In DeInitialize, perform any cleanup necessary for the lookup module.

Any destruction that must not be performed in DllMain (thread destruction, synchronization, etc.) should be performed here. JAWS calls DeInitialize after all use of the lookup module is complete, immediately prior to calling FreeLibrary.

Return Value

Return S_OK (0x00000000L) if deinitialization is successful, otherwise E_FAIL (0x80004005L).

GetInterfaceSchema

In GetInterfaceSchema return the numeric version of the supported interface. The interface version specified in this documentation is 1. Should additional functions later be supported, the interface version should increment.

Syntax

HRESULT GetInterfaceSchema(
DWORD& dwSchema
);

Parameters

dwSchema [out]
dwSchema will receive the API schema supported by the Lookup Module.

Return Value

If the function succeeds, the return value is S_OK (0x00000000L). Otherwise, return a non-zero value.

GetFriendlyName

GetFriendlyName should return the friendly name(s) for a lookup module or the rule sets belonging to the module.
If a lookup module has no rule sets associated with it, return the localized name for the lookup module.
If a lookup module has rule sets, it returns a bar-delimited list of colon-delimited file name:friendly name pairs for the lookup module.

Example:

LRL_MLB:MLB|LRL_NFL:NFL|LRL_Wiki:Wikipedia

Syntax

HRESULT GetFriendlyName (
LPWSTR lpszName,
DWORD& dwSize
);

Parameters

lpszName [out]
A pointer to a buffer that receives a localized name for the module or file name-friendly name pairs for supported rule sets.

dwSize [in, out]
The size of the lpszName buffer in wide chars. If the output data is larger than the supplied buffer, upon return, this variable should be set to the required size.

Return Value

If the function succeeds, return S_OK (0x00000000L). Otherwise, return one of the following errors:

E_INVALID_ARG (0x80070057L)
lpszName is NULL or dwSize is 0.

E_INSUFFICIENT_BUFFER (0x802A0001L)
lpszName is not large enough to hold the return data. Set dwSize to the required size.

Describe

Implement Describe to return a localized description of the lookup module or specified rule set.
HRESULT Describe (
LPCWSTR lpszRuleSet,
LPWSTR lpszOut,
DWORD& dwSize
);

Parameters

lpszRuleSet [in, optional]
Return a null terminated string containing the name of the RuleSet for which the description should be returned. If this value is null, then the general description for the lookup module should be returned.

lpszOut [out]
A pointer to a buffer that receives the output data.

dwSize [in, out]
The size of the lpszOut buffer in wide chars. If the output data is larger than the supplied buffer, upon return, this variable should be set to the required size.

Return Value

If the function succeeds, return S_OK (0x00000000L). Otherwise, return one of the following errors:

E_INVALIDARG (0x80070057L)
Use this to indicate an invalid argument.

E_RULESET_NOT_FOUND (0x802A0002L)
The rule set specified by lpszRuleSet is not supported by the lookup module.

E_INSUFFICIENT_BUFFER (0x802A0001L)
lpszName is not large enough to hold the return data. Set dwSize to the required size.

Invoke

Implement Invoke to perform the lookup work for your module. Invoke should perform the work synchronously.

Syntax

HRESULT Invoke (
LPCWSTR lpszRuleSet,
LPCWSTR lpszIn,
LPCWSTR lpszContext,
DWORD dwOffset,
LCID lcidAppLocale,
LPWSTR lpszOut,
DWORD& dwSize,
LPVOID lpExtra = NULL
);

Parameters

lpszRuleSet [in, optional]
An optional null-terminated string that contains the name of the rule set that the lookup module must use to perform the query.

lpszIn [in]
A null terminated string containing the input data for the query. This may be the word or phrase at the current cursor. This value may be NULL if the lookup module utilizes the Context and Offset arguments.

lpszContext [in]
A null terminated string containing context data for the query. For example, some lookup modules may utilize the sentence or paragraph containing the target word. This argument can be NULL.

dwOffset [in]
The 0-based offset of the targeted word in lpszContext. 0xffffffff indicates no offset.

lcidAppLocale [in]
The locale ID of the calling application. This will allow you to select an appropriate localized lookup source, display a localized UI, or return error messages in the application’s language.

lpszOut [out]
A pointer to a buffer that receives the output data. Depending on the lookup module, this could be an error, command, replacement string, etc.

Note: It is recommended you always place error text if your dll raises an error, because the Debug tool can be used to see what went wrong from the scripts, e.g. unexpected query search term or form / syntax / grammar errors in rule set files if your dll uses a rule set format.

dwSize [in, out]
The size of the lpszOut buffer in wide chars.

lpExtra [in]
This argument may be optionally used to pass additional information to the lookup module. The content and format of the data depends on the requirements of the lookup module. The value can be NULL.

Return Value

If the function succeeds, return S_OK (0x00000000L). Otherwise, return one of the following errors as appropriate to your module:

E_INVALIDARG (0x80070057L)
The rule set specified by lpszRuleSet is not supported by the lookup module.

E_INSUFFICIENT_BUFFER (0x802A0001L)
lpszName is not large enough to hold the return data. In this case, set dwSize to the required buffer size (in characters including the null terminator) required to hold the data.

E_RULESET_NOT_FOUND (0x802A0002L)
The requested rule set was not found.

E_REQUEST_FAILED (0x802A0003L)
The lookup attempt failed.

E_REQUEST_NO_RESULTS (0x802A0004L)
The lookup succeeded, but there were no results for the search term.

E_REQUEST_TIMEOUT (0x802A0005L)
The lookup took longer than the allowed amount of time.

Built-in Script API

Built-in functions are functions created by Freedom Scientific developers. They are used as building blocks for your scripts and functions. Although built-in functions can be used anywhere, they cannot be modified.

For an introduction to the Freedom Scientific scripting language, refer to the Basics of Scripting manual on the Freedom Scientific Web site. It provides detailed information on scripting terms, syntax, functionality, and more. There are also numerous exercises to help you practice what you have learned. The Basics of Scripting manual is available in HTML Help format.

The following built-in script functions are available for Research It.

LRL_GetPrimaryLookupModule

The primary lookup module is the one designated to be used when the user single presses the LookupModuleInvoke keystroke. The PrimaryLookupModule key is stored in the JAWS Configuration File [options] section. The key may be application specific.

Syntax

int GetPrimaryLookupModule (
String BYREF strLookupModule,
String BYREF strRuleSet
)

Parameters

strLookupModule [out]
A string that will receive the name of the primary lookup module.

strRuleSet [out]
A string that will receive the rule set name of the primary lookup module. If there is no rule set, the string will be set to “”.

Return Value

If the function succeeds, TRUE (1) is returned. Otherwise FALSE (0) is returned.

LRL_GetFirstLookupModule

LRL_GetFirstLookupModule is used to begin an iteration through the active lookup module/RuleSet combinations. LRL_GetFirstLookupModule will return an index which can be used in the argument to LRL_GetNextLookupModule.

Syntax

LRL_GetFirstLookupModule (
String BYREF strLookupModule,
String BYREF strRuleSet
)

Parameters

strLookupModule [out]
A string that will receive the name of the first lookup module/rule set combination.

strRuleSet [out]
A string that will receive the rule set name of the first lookup module/rule set combination. If there is no rule set, the string will be set to “”.

Return Value

If the function succeeds, TRUE (1) is returned. Otherwise FALSE (0) is returned. If TRUE is returned, the return value can be passed to LRL_GetNextLookupModule to retrieve the next lookup module/rule set combination.

LRL_GetNextLookupModule

LRL_GetNextLookupModule is used to continue an iteration through the active lookup module/RuleSet combinations.

Syntax

LRL_GetFirstLookupModule (
int nDex,
String BYREF strLookupModule,
String BYREF strRuleSet
)

Parameters

strLookupModule [out]
A string that will receive the name of the next lookup module/rule set combination.

strRuleSet [out]
A string that will receive the rule set name of the next lookup module/rule set combination. If there is no rule set, the string will be set to “”.

Return Value

If the function succeeds, TRUE (1) is returned. Otherwise FALSE (0) is returned.

LRL_Invoke

Invoke performs a request from a lookup module.

Syntax

int LRL_Invoke (
String strModuleName,
String strRuleSet,
String strIn,
String strContext,
Int nOffset,
String BYREF strOut,
String strExtra
);

Parameters

strModuleName [in]
A string that contains the name of the lookup module.

strRuleSet [in]
A string that contains the rule set specifier that the lookup module may use to perform the query. This string may be “” if no rule set applies.

strIn [in]
A string containing the input data for the query. This may be the word or phrase at the current cursor. This value may be “” if the lookup module utilizes the Context and Offset arguments.

strContext [in]
A string containing context data for the query. For example, some lookup modules may utilize the sentence or paragraph containing the target word. This argument can be “”.

nOffset [in]
The 0-based offset of the targeted word in lpszContext. -1 indicates no offset.

strOut [out]
A string that will be populated with the returned text.

String strExtra [in]
A string that may be populated with custom formatted, lookup module specific information. For example, a translation lookup module may include information about the input and output locales for the translation. This string may be “”.

Return Value

If the function succeeds, TRUE (1) is returned. Otherwise one of the following error codes is returned:

E_INVALIDARG (0x80070057L)
Use this to indicate an invalid argument.

E_RULESET_NOT_FOUND (0x802A0002L)
The requested rule set was not found.

E_REQUEST_FAILED (0x802A0003L)
The lookup attempt failed. Indicates a malformed query.

E_REQUEST_NO_RESULTS (0x802A0004L)
The lookup succeeded, but there were no results for the search term.

E_REQUEST_TIMEOUT (0x802A0005L)
The lookup took longer than the allowed amount of time.

Script Wrapper Functions

void RunLookupModuleQuery(string strQuery, string sRuleSet, string sModule, string strError)

Return Type: void

Parameters:

string strQuery
The text to send to the lookup module and rule set combination.

string sRuleSet
The rule set to apply to the supplied Lookup module. If no module was supplied, the FSLookup module will be used. Leave this param blank if you are using the primary (default) or your module does not accept rule sets.

string sModule
Optional lookup module to use. If not supplied, the FSLookup Module will be used.

string strError
optional error string to use if the query causes Invoke to return non-0 or the string is empty

Description: Run Query either based on the supplied lookup module / rule set combination, or one or more of the optional parameters. You can leave both Rule set and Module blank to use the primary lookup module, or fill in one or both parameters. Fill in just he rule set parameter if you want to use the FS Lookup module. This is the case unless you have written or been supplied with a module dll using the Live Resource Lookup API. Most rule sets that apply to web services will use FSLookup (the default).

void RunLookupModuleQueryUsingListOfModules(string strQuery)

Return Type: void

Parameters:

string strQuery
The query to use - generally the word or selection at the active cursor.

Description: Generates a list of rule set - lookup module combinations, and generates a query based on the incoming text and the user's choice from the list.

void DebugLookupModuleQueryUsingListOfModules()

Return Type: void

Description: Debug output for rule set. Error codes / text are placed in the Virtual Viewer for developers of rule sets and/or modules. This function only displays what's thrown up by Invoke calls. No parameters, as it runs as a stand-alone providing both a list of available rule sets and a prompt to enter the search term. To make your rule set discoverable first, put at least a dummy version of the files into the RuleSets folder of your subdirectory. Then go to Configuration Manager | Research It options and make sure yours is checked, so it's available for listing. When asked for the search term, press ESC to send a blank string, or type the term and press ENTER.