Web Scripting

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 CONTROL + 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 textcolorbbeK to move to the next PlaceMarker, or press SHIFT + K to move to the prior PlaceMarker. Press CONTROL + 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 Move your cursor to the location on the page where you want to put the PlaceMarker Press CONTROL + SHIFT + K 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 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.

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 JAWSKEY + 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 JAWSKEY + F2.

  2. Select Settings Center, and press ENTER.

  3. Focus is in the Search edit box. Type in "Summary" 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.

Additional Practice: Design a custom page summary template that adapts per site (for example, news site vs. portal). What rules and data would you include, and how would you maintain them over time?

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 JAWSKEY + 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.

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 JAWSKEY + 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.

Additional Practice: Create a labeling pass for a complex site: identify poorly labeled controls and assign consistent custom labels. How will you export or import labels across profiles or machines?

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.

Open Internet Explorer and open the JAWS Script Manager.

  1. Press CONTROL + HOME to move to the bottom of the script file and press ENTER to create a new line.

  2. Press CONTROL + E to activate the New Script dialog.

  3. Give the script a name of TestBed and assign it to the keystroke CONTROL + SHIFT + T.

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

Additional Practice: Build a minimal labelling toolbox using the TestBed script (for example, quick actions to list headings, form fields, ARIA roles). How could you make it discoverable and low-friction?

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 CONTROL + S to compile it.

PerformScript DisplayBasicElementInfo ()

You can now move to any HTML element on a web page and press CONTROL + 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.

Additional Practice: Compose a composite script that speaks and/or copies key attributes (role, name, value, index) and optionally copies them to the clipboard. Which functions would you combine and why?

Automatically Filling Out Form Information

Scripting can be used to automatically fill out information in a form. This can save users a great deal of time when there is a need to fill out repetetive pieces of information. The following web page will be used for this example Web track sample form on Surf's Up.

The purpose of this script is to automatically fill out two pieces of information in the Web Track sample form. Before writing the script it is important to examine the layout and order of the form. In our script we want JAWS to automatically ENTER the name and phone number and then activate the Mailing Address button. Although there are many other form fields available on the form, for the purpose of this script we will stick with just the name and phone number boxes.

The following is a list of some of the functions and scripts we will use in this exercise.

  1. ExitFormsMode: Script that performs all actions related to exiting forms mode

  2. MoveToFormField: Depending on the value of the SearchOption parameter, positions to the first, last, next, or prior form field on the current web page

  3. MoveToFormFieldByIndex: Moves to a specific form field based on the index provided

  4. TurnOnFormsMode: Turns on forms mode

  5. Delay: Lets the script pause for a specified number of milliseconds

  6. GetDocumentPath: Returns the URL of the current document

  7. TypeString: Types a string of text just as if it were entered from the keyboard

  8. TypeKey: Simulates a keyboard command

Creating the Script

We start by creating a blank script with the name FormFiller and assigning it to the keystroke CONTROL + SHIFT + F. Be sure to add an appropriate synopsis and description.

Writing the Script The first thing our script needs to do is move the virtual cursor to the first form field on the page. This is accomplished using the MoveToFormField function. In order to tell JAWS we want to move to the first field on the page, we pass the S_Top constant as the first parameter to the function.

Once the cursor is located on the edit field we use the TurnOnFormsMode function to activate forms mode. We can then use TypeString to type some text into the edit box.

Before moving the cursor to the next form field to ENTER the phone number, we must first exit out of forms mode in order to reactivate the virtual cursor. This is done by using the PerformScript statement to call the ExitFormsMode script. Depending on the speed of the computer your script is running on it may be necessary to use the Delay function to let the script pause for a couple of milliseconds after the TypeString function and before exiting forms mode. If you're unsure as to whether or not a delay is needed you can try it without a delay and see if it works. It may also be necessary to insert another delay after the ExitFormsMode script is run. This gives the computer time to perform the actions needed to exit forms mode and reactivate the virtual cursor.

We can now use the MoveToFormFieldByIndex function to move the cursor to the phone number edit box. Pass the number 2 as the parameter to MoveToFormFieldByIndex to tell JAWS to move to the second form field on the page. This is the phone number edit box. Note that it may be necessary again to call the Delay function in order to give the computer time to keep up with your script.

After activating forms mode again you can use the TypeString function to type out the phone number. You can then use several of the steps above to delay the script and then exit forms mode.

Finally, you use the MoveToFormFieldByIndex function again to jump directly to the Mailing Address button. The index of the button is 7 which you can determine by counting the number of fields on the page. For example, the first field has an index of 1, the second has an index of 2 and so on. Once the cursor is positioned on the button you can use the TypeKey function and pass the string "SPACEBAR" to have your script simulate a SPACEBAR press.

Identifying the Document URL

The script that we have written is only going to work if we are on the page with the Web Track sample form. If we are on any other page there could be unintended consequences or errors. We can use the GetDocumentPath function to determine if we are on the correct page before we execute any of the steps in our script. If we are not on the correct page, we can alert the user and exit the script.

Enhancing the Script

You may notice that JAWS speaks extra information while the script is running. JAWS automatically speaks because the script is causing various events to fire that cause messages to be spoken. You can use the SpeechOff function to turn off speech while JAWS is moving to the form fields and then use SpeechOn to turn it back on again.

The Script Code

The following is the script in its entirety.

Script FormFieldEntry () ; Assign To CONTROL + SHIFT + F
If GetDocumentPath () != "http://www.freedomscientific.com/Training/Surfs-Up/WebTrack.htm" Then
    SayFormattedMessage (OT_Message, "This Script is only available On the Web Track sample form", "Not available")
    Return
EndIf
SpeechOff (False)
MoveToFormField (s_top)
TurnOnFormsMode ()
TypeString ("Ryan Jones")
Delay(2)
PerformScript ExitFormsMode ()
Delay (2)
MoveToFormFieldByIndex (2)
Delay(2)
TurnOnFormsMode ()
Delay(2)
TypeString ("800-444-4443")
PerformScript ExitFormsMode ()
Delay(1)
MoveToFormFieldByIndex (7)
SpeechOn ()
TypeKey ("SPACEBAR")
EndScript

Additional Practice: Generalize the form filler to load field values from a configuration file and handle field order changes. How would you detect failures and recover gracefully during automation?

Automatically moving to a Placemarker When a Page Loads

The purpose of this exercise is to have JAWS automatically move the cursor to the location of a placemarker each time the page loads. This benefits the user in that there is no need to press a keystroke to move the cursor to the placemarker. We will use the Freedom Scientific HOME. page for this exercise.

  1. We first need to put a placemarker at the spot we want the cursor to jump to each time. On the Freedom Scientific HOME. page, move to the level two heading called "Latest news" and add a temporary placemarker by pressing CONTROL + WINDOWS + K.

  2. In order to make JAWS move to the placemarker automatically, we need to modify the DocumentLoadedEvent. This is a default event function that fires each time a web page is loaded. A custom version of DocumentLoadedEvent is located in Internet Explorer.jss so we can simply modify this event function and add our own statements at the end.

  3. Locate DocumentLoadedEvent and insert a blank line right before the EndFunction statement. This is where we will add our own statements so as not to interfere with the default processing of the function.

    As with the previous exercise it is important to insure our statements only run on one particular page and not on every page we open. We can use the GetDocumentPath function in an If-Then statement to insure we are on the page http://www.freedomscientific.com/default.asp.

  4. We can now use the MoveToPlaceMarker script and pass it the number one to tell JAWS to move to the first placemarker on the page. Because MoveToPlaceMarkerN is a script and not a function, we use the PerformScript statement to call it.

The Script Code The additional code added at the bottom of Documentat LoadedEvent in Internet Explorer.jss should look like the following:

If GetDocumentPath () == "http://www.freedomscientific.com/default.asp" Then
    PerformScript MoveToPlaceMarkerN (1)
EndIf

One added bonus to using a temporary placemarker verses a permanent one is that if we move the placemarker on the page, JAWS will then jump to that spot each time the page loads. This prevents you from having to modify the script if you want JAWS to automatically move to a new spot when the page loads.

Additional Practice: Extend this behavior to multiple pages with different targets; design a mapping of URL patterns to placemarker indices or names. How would you implement and maintain this mapping?