Writing Scripts for Web Pages with JAWS and MAGic, an Introduction - Part 1

NOTE: For those of you participating in the live Webinar, the following link will open the documentation in a new browser window.

Introduction

In this two part series on writing scripts for web pages we will explore the use of the JAWS and MAGic scripting language for providing more efficient access to web page information. We will look at a variety of different scripts and functions designed to locate information on web pages. We will first however explore some of the non-scripting related ways to navigate web pages more effectively.

Placemarkers

PlaceMarkers allow you to quickly and easily navigate to commonly used areas of your favorite Web pages or HTML documents. You can use PlaceMarkers to jump between certain areas of a page, mark important sections of an HTML document, or indicate key form elements. For example, you could use PlaceMarkers to move to required fields in a complicated form or specific paragraphs in a long HTML document.

There are two types of PlaceMarkers, fixed and temporary. Only one Temporary PlaceMarker can exist at a time but you can move it simply by dropping it in a new location. You drop the Temporary PlaceMarker by pressing CTRL+WINDOWS+K. If you then move to some other place and press the same keystroke again, it will remove the Temporary PlaceMarker from the previous location and place it at the current location. The Temporary PlaceMarker, if assigned, will also appear in the List of PlaceMarkers discussed below.

When you open a Web page press K to move to the next PlaceMarker, or press SHIFT+K to move to the prior PlaceMarker. Press CTRL+SHIFT+K to display a list of all PlaceMarkers on the current page. Use the UP/DOWN ARROW keys to select a PlaceMarker in the list. Then press ENTER to activate the Move To button. You can also press TAB to move to the Move To button and press SPACEBAR on it or press ALT+M to activate it and move your cursor to the PlaceMarker's location on the page.

Adding PlaceMarkers

  1. Move your cursor to the location on the page where you want to put the PlaceMarker
  2. Press CTRL+SHIFT+K
  3. Press SPACEBAR on the Add button or press ALT+A. JAWS suggests a name for the PlaceMarker based on the text present at your cursor's current location. You can enter a new name if necessary
  4. Press SPACEBAR on the OK button to add the PlaceMarker to this page

NOTE: Use the Anchor to Text checkbox in the Add Placemarker dialog box to tie a placemarker to a specific word or phrase. This will keep the placemarker in the proper place even if the location of the text changes on the page.

Follow along with the instructor to practice putting a placemarker at the beginning of the search results in Google.

The Custom page Summary

Use the Custom Page Summary to have JAWS read the contents of placemarkers on a page when the page loads. The information can either be spoken or placed in the virtual viewer for reading. To temporarily turn on the Custom Page Summary, press INSERT+V and modify the Custom Page Summary option found in the list. Follow the steps below to permanently change the setting.

  1. In Internet Explorer, press INSERT+F2.
  2. Select Settings Center, and press ENTER.
  3. Focus is in the Search edit box. Type in "custom placemarker page" without the quotes.
  4. Press DOWN ARROW to move to "Custom PlaceMarker Page Summary" in the filtered results of the tree view in Settings Center.
  5. Press SPACEBAR to choose to speak, list, or ignore PlaceMarkers. If you choose List PlaceMarkers in virtual viewer on page load, JAWS reads the custom PlaceMarker page summary and displays the information in the virtual viewer.
  6. Press TAB to move to the OK button and activate it with the SPACEBAR. The changes are made and saved. Settings Center closes.

Custom Labels

JAWS allows you to assign custom text labels to almost any HTML element that you can move to by pressing the TAB key in Internet Explorer and Web-based documents. These elements include text links, graphic links, form fields, and buttons. You can also label images on Web pages. JAWS reads these custom labels instead of the identifying text assigned to the elements by the Web page author. JAWS also uses custom labels to identify elements when they appear in lists, such as the list of form fields that displays when you press INSERT+F5. You can use this feature to customize the elements of any Web page to help you navigate the page, reduce verbosity, compensate for incomplete or poorly labeled elements, and similar functions.

NOTE: You can also use this feature to label form fields in Microsoft Word and Adobe Acrobat or Reader.

JAWS saves the labels you assign to a Web page so they are available each time you use that page. In addition, the labels you create are applied to identical elements any time they appear in that page's domain. For example, if you assign a label to a button, JAWS reads that label any time you encounter the button on any Web page within that domain. Custom labels are saved in JSI files in the Settings\Enu\PersonalizedSettings folder.

Perform the following steps to add a custom label to an item on a web page.

  1. Move the JAWS virtual cursor to the element you wish to label.
  2. Press INSERT+F2 to open the list of JAWS managers.
  3. Activate the Custom Label item in the list.
  4. Type the text of the new label and press ENTER to activate the OK button.

The FSDN

The Freedom Scientific Developers Network (FSDN) is a HTML style help system containing reference information for the built-in and user defined functions and scripts that come with JAWS. You can also use this as a reference when scripting for MAGic or the PAC Mate Omni. You can download the latest version of the FSDN from the Freedom Scientific website.

Use the ARROW KEYS to navigate through the table of contents pane and press ENTER on a topic to display it in the reading pane. Press F6 to move the cursor to the reading pane to have JAWS read it. Navigate to the following book to view a list of topics related to HTML.

Scripting | Reference Guide | JAWS | HTML

Exploring Various HTML Related Functions

Before we explore some of the scripts and functions designed to work in the HTML environment, we first need to create a test script we can use in Internet Explorer. Perform the following steps to create this script.

  1. Open Internet Explorer and open the JAWS Script Manager.
  2. Press CTRL+HOME to move to the bottom of the script file and press ENTER to create a new line.
  3. Press CTRL+E to activate the New Script dialog.
  4. Give the script a name of TestBed and assign it to the keystroke CTRL+SHIFT+T.

We can now use this script as a testing ground for some of the HTML related scripts and functions found in the FSDN.

DisplayBasicElementInfo Script

The DisplayBasicElementInfo script displays a description of the current HTML element the cursor is on, along with a description of its parent elements. This script can be useful in examining the structure of a HTML document. The text is displayed in the virtual viewer. Insert the following statement into the body of the TestBed script and press CTRL+S to compile it.

PerformScript DisplayBasicElementInfo ()

You can now move to any HTML element on a web page and press CTRL+SHIFT+S to find out information on its attributes.

GetElementDescription

The GetElementDescription function is similar to the DisplayBasicElementInfo script accept that it returns a string with the text rather than displaying it in the virtual viewer. Since the function returns a string, it can be used as a parameter to one of the speaking functions such as SayString. Use the two parameters of the function to determine if you want ancestor information and values for the attributes spoken.

DocumentLoadedEvent

The DocumentLoadedEvent function fires each time a web page loads. This may be useful if you want to run script code when a page loads (before the user presses any keystrokes). For example, you could modify the DocumentLoadedEvent function to speak a message with specific navigation tips when a web page first loads. There is a custom version of DocumentLoadedEvent found in the Internet Explorer script file.

IsEmptyEditFormField

This function returns true if the form field that has focus is empty of text. If there is text in the form field, this function returns false. Note that forms mode does not have to be on for this function to work properly but the virtual cursor must be placed on an edit field when the function is called.

MoveToFormField

This function can move the cursor to the first, last, next, or previous form field on a web page. The function requires a parameter indicating in which direction to look for the next field. This can be useful if your script is designed to automatically input information into a form.

MoveToHeading

This function can move the cursor to the first, last, next, or previous heading on a web page. You can also specify which level of heading to move to (i.e. one through six). The function returns true if the heading was found or false otherwise.

TurnOnFormsMode

This function turns on forms mode just as if the user pressed ENTER. This function is especially useful when automatically filling out forms with a script.

ExitFormsMode Script

This script does the necessary processing to exit forms mode. Use the PerformScript statement to call this script. This script is especially useful when automatically filling out forms with a script.

Prior page

Next page