To show how to implement a custom name generator, we will start with an example menu element:

<SPAN class='menu' id='fileMenu'>
    <SPAN class='menuItem' menuID='fileOpen'>Open</SPAN>
    <SPAN class='menuItem' menuID='fileQuit'>Quit</SPAN>
</SPAN class='menu'>

First, we must register the menu items as clickable widgets using the Squish.registerWidget() function:

Squish.registerWidget({Class: "menuItem", Event: "click"});

(We already saw an example of using this function earlier: How to set up Support for Simple Widgets (Section 15.9.2).)

In this example we are going to use the menuID attribute, along with the DOM class, and the parent element's ID, to give our menu elements (i.e., each menuItem <span> tag), their unique identifying names.

var myUiExtension = new Object;

myUiExtension.nameOf = function(obj) {
    if (obj.tagName == "SPAN" && Squish.hasClassName(obj, "menuItem")) {
        var name = '{';
        name += Squish.propertiesToName(obj, ["tagName", "menuID"]);
        name += " parentID='" + obj.parentNode.id + "'";
        name += " className='menuItem'";
        name += "}";
        return escape(Squish.uniquifyName(name, obj));
    }
    return undefined;
}

We have added this function as a property of a custom myUiExtension object. In the implementation we check if the object is an object of the type we want to handle, that is, menuItem <span> tag. If the type is right we use custom code to create a unique name for it; otherwise we return undefined—this isn't a valid name value, so Squish will try each of the other registered name generation hook functions (if any), and if all of them return undefined (or if there aren't any), Squish will fall back to using its own default name generator.

To determine if the element is one of those we want to handle, we check to see if its tag name is SPAN and if its DOM class is menuItem. For this second check we use the Squish.hasClassName() helper function, which returns a true value if any of the DOM object's DOM classes has the same name as the given class name.

If the element is of the right type we create a name for it using our own custom name generation algorithm. A name consists of one or more property name–value pairs, all contained in braces. Here we start by using the Squish.propertiesToName() function to create a name string containing the given property names and values; then we add two additional property pairs, one for the parent ID and another for the class name. Finally, we use the Squish.uniquifyName() function to ensure that we produce a unique name. This function accepts a real name as a string and the object the name is supposed to identify, and will return the name unchanged if possible, or will return it with the addition of an occurrence property if it is necessary to distingish the name further to ensure its uniqueness.

So, given the example shown above, if the object was the fileOpen menu item, the Squish.propertiesToName() function would give us the string "tagName='span' menuID='fileOpen'", and with the addition of the parent ID and class name, the final name we would end up with is "{tagName='SPAN' menuID='fileOpen' parentID='fileMenu' className='menuItem'}".

We could not use the Squish.propertiesToName() function for either the parent ID or for the class name properties. In the case of the parent ID this is because the parentID is not a regular property, but rather a pseudo-property, so we must handle it ourselves. Once part of a real name though, Squish will be able to work with it like any other property. In the case of the class name the only reason we cannot use the Squish.propertiesToName() function is because the DOM property name is class while Squish uses the JavaScript className name. Also, a DOM class may contain multiple values while we only want to specify one— menuItem.

At the end we make sure that any special characters are escaped properly—for this we use the standard JavaScript escape() function. And then we return the result.

Once our name generator function is ready, we must inform Squish of its existence so that it is used when names are needed. This is done by registering it as a hook function:

Squish.addNameOfHook(myUiExtension.nameOf);

Here we have used the Squish.addNameOfHook() function to register the myUiExtension.nameOf() function as a name generator function. From now on Squish will use this function whenever it needs to generate a real name, but falling back on any other generator function (and its own built-in default name generator function as a last resort), if the function returns undefined.

When searching for an object by name, Squish iterates over all objects in the DOM tree and queries the specified object properties to see if their values match those of the name.

Using a custom name matcher hook makes it possible to consider a name's pseudo-properties (such as the parentID we saw earlier), when searching for a matching object. Since Squish has no knowledge about any pseudo-properties we have created, we must implement a custom function to perform the lookup and name matching and that accounts for our pseudo-properties.

myUiExtension.matchObject = function(obj, property, valueObject) {
    if (property == "parentID")
	return Squish.matchProperty(valueObject, obj.parentNode.id);
    return undefined;
}

Again, we have implemented this function as a property of our custom myUiExtension object. Squish will pass the object, the property name and the expected value as specified in the name to this function.

If the given property is our pseudo-property, we use Squish's built-in Squish.matchProperty() function to determine if there is a match. Otherwise we return undefined; in such cases Squish will try all the other match objects that are registered (if any), and if none of these gives a definitive true or false (or if there aren't any), it falls back on its own internal name matching function. Note that the valueObject is not simply a string but rather an object which contains a string value and a flag denoting whether the matching should be based on a literal string comparison, wildcard matching, or regular expression matching. (See also Improving Object Identification (Section 16.8).)

In this example we have chosen to handle the parentID pseudo-property ourselves; and by returning undefined for any other property we pass on the matching work to Squish for anything other than the pseudo-property we are interested in.

The custom name matching setup is completed by installing the hook:

Squish.addMatchObjectHook(myUiExtension.matchObject);

The Squish.addMatchObjectHook() function can be used to register as many name matching functions as we want.

Before we can start implementing the necessary support, we need to look at the widget's DOM structure since our custom support will use the Web application's DOM internally to provide the abstraction and encapsulation that test scripts will rely on.

Below is a screenshot of the GWT Tree widget as it appears in a Web browser:

The GWT Tree widget

The DOM hierarchy that GWT uses to represent this tree widget has the following structure (with irrelevant details, and most of the data, omitted):

<DIV class="gwt-Tree">
    <TABLE>
        <TR>
          <TD">
            <IMG src="tree_open.gif"/>
          </TD>
          <TD>
            <SPAN class="gwt-TreeItem">Beethoven</SPAN>
          </TD>
        </TR>
    </TABLE>
    <SPAN>
      <DIV>
        <TABLE>
            <TR>
              <TD>
                <IMG src="tree_closed.gif"/>
              </TD>
              <TD>
                <SPAN class="gwt-TreeItem gwt-TreeItem-selected">Concertos</SPAN>
              </TD>
            </TR>
          </TBODY>
        </TABLE>
      </DIV>
      <DIV>
        <TABLE>
            <TR>
              <TD>
                <IMG src="tree_closed.gif"/>
              </TD>
              <TD>
                <SPAN class="gwt-TreeItem">Quartets</SPAN>
              </TD>
            </TR>
          </TBODY>
        </TABLE>
      </DIV>
    </SPAN>
    ...
</DIV>

So we can see that a tree widget is represented using a DIV element with the class name of gwt-Tree. The tree itself is contained inside this DIV element, in a TABLE.

Each tree item is held in a SPAN element that has a class of gwt-TreeItem. The item's text is the element's inner text, and selected items have an additional class of gwt-TreeItem-selected.

Item handles (typically shown as + or - symbols to indicate that the item can be expanded or is already expanded), are represented by an IMG element in the TD element above the item—specifically, the item's parent's previous sibling's first child. The IMG's src property can be used to determine if the item is expanded (src="tree_open.gif") or collapsed src="tree_closed.gif").

The relationship between the items (i.e., the actual tree structure), is modeled using nested SPAN elements which contain a set of siblings relative to their parent.

This information is sufficient for us to be able to detect a GWT Tree element, the tree's item elements, and the items' handles, in the web page's DOM structure. Armed with this knowledge we can create a high-level API that our test scripts can use to interact with a GWT Tree and its items, using Squish's uniform “item view” API.

Note that all the code used in the following subsections is taken from the file lib/extensions/web/jshook_gwt.js.

	Functions to implement in the toolkit's extension object
	eventObject(object) typeOf(object) nameOf(object)

The first step is to implement the JavaScript hooks for recording high-level GUI operations on the GWT Tree. This means, if the user clicks an item, a clickItem(treeName, itemName) function call should be recorded. Similarly, a click on a tree item's handle should be recorded as clickTreeHandle(treeName, itemName).

To achieve this, we must implement three different hooks:

Once these functions are implemented, they must be registered with Squish so that they are called by Squish's event recorder. When Squish calls them, it will pass the event's DOM source object as an argument, and based on this we can decide whether we will respond or not. (We can safely ignore events we don't want to handle and leave them to Squish to deal with.)

For the GWT Tree when we implement these functions we must handle three different high-level objects:

So for all three functions we need a way to determine which type of object we are dealing with. To do this we will start by defining a gwtExtension object to contain all the GWT Tree-related code we write. Then we'll define some constants, and then we will create a getType() function.

var gwtExtension = new Object;

gwtExtension.Tree = 0;
gwtExtension.TreeItem = 1;
gwtExtension.TreeItemHandle = 2;

We will use these constants to distinguish between the objects we are interested in handling. Now we need a function that can match DOM class names to these constantts:

gwtExtension.getType = function(obj)
{
    if (Squish.hasClassName(obj, 'gwt-TreeItem'))
        return gwtExtension.TreeItem;
    else if (obj.tagName == 'IMG' &&
             (obj.src.indexOf('tree_open') != -1 || obj.src.indexOf('tree_closed') != -1) && 
             Squish.hasClassName(gwttreeExtension.itemOfHandle(obj), 'gwt-TreeItem'))
        return gwtExtension.TreeItemHandle;
    else if (Squish.hasClassName(obj, 'gwt-Tree'))
        return gwtExtension.Tree;
    return undefined;
}

The custom getType() function uses Squish's Squish.hasClassName() function to see if the element is a tree item, and if it is, the appropriate constant is returned. Similar code is used to handle trees themselves, but for tree handles we must check that the tag is IMG and that it has one of the appropriate images and that the element associated with the image is an item with the correct class (gwt-TreeItem). We will see the creation of the gwttreeExtension object and of the gwttreeExtension.itemOfHandle() function shortly.

If the element is not one of those we are interested in, we return undefined which indicates to Squish that it should try whatever type functions it hasn't yet tried, or to fall back on its own built-in functionality.

Now that we have a suitable getType() function, it is quite easy to implement the three hook functions that are needed:

gwtExtension.eventObject = function(obj)
{
    if (!obj)
        return undefined;

    switch (gwtExtension.getType(obj)) {
        case gwtExtension.TreeItem: // fallthrough
        case gwtExtension.TreeItemHandle:
            return obj;
    }

    return undefined;
}

If the high-level object type is a tree item or a tree item's handle, we return this object. This tells Squish that the object is one we want to record events on, and so should not be ignored by the event recorder. As usual, if we don't recognize the object, we return undefined which tells Squish to handle it for us.

If Squish encounters an object for which events should be recorded, it will need know the object's type. For this we must implement a suitable hook function:

gwtExtension.typeOf = function(obj)
{
    switch (gwtExtension.getType(obj)) {
        case gwtExtension.TreeItem:
            return 'custom_item_gwttree';
        case gwtExtension.TreeItemHandle:
            return 'custom_itemhandle_gwttree';
        case gwtExtension.Tree:
            return 'custom_itemview_gwttree';
    }

    return undefined;
}

The type names returned from this function follow a convention that must be followed! Squish provides a common item view abstraction, and for it to work correctly, we must return type names of the correct form.

The three main components used by the item view API for custom trees, and that correspond to components that the DOM object represents, are items, handles, and views—a view is a list or table or tree widget. The naming convention we must follow for custom type names is very simple: Item type names must begin with custom_item_; Item handle type names must begin with custom_itemhandle_; and view type names must begin with custom_itemview_. The rest of the name must identify our custom view (so in this example, each type name ends with _gwttree).

The third hook function that we must implement returns the name of a specific high-level object:

gwtExtension.nameOf = function(obj)
{
    switch (gwtExtension.getType(obj)) {
        case gwtExtension.TreeItem:
            return escape(gwtExtension.nameOfTreeItem(obj));
        case gwtExtension.TreeItemHandle:
            return escape(gwtExtension.nameOfTreeItem(gwttreeExtension.itemOfHandle(obj)));
        case gwtExtension.Tree:
            return Squish.uniquifyName(gwtExtension.nameOfTree(obj), obj);
    }
	
    return undefined;
}

As usual, we tell Squish to handle any objects that we are not interested in by returning undefined.

This function makes use of two other functions, gwtExtension.nameOfTree() and gwtExtension.nameOfTreeItem() to create suitable real (multi-property) names for the custom objects. Here are their implementations:

gwtExtension.nameOfTree = function(obj)
{
    return '{' + Squish.propertiesToName(obj, ["tagName", "id", "name"]) + "className='gwt-Tree'}";
}

This function creates a unique name for each GWT Tree object that Squish encounters. (See How to Implement a Custom Name Generator (Section 15.9.3.1) for more information about creating names.)

Here is the function which generates a name for a tree item:

gwtExtension.nameOfTreeItem = function(obj)
{
    var tree = obj;
    while (tree && (!Squish.hasClassName(tree, 'gwt-Tree')))
	tree = tree.parentNode;
    var treeName = Squish.nameOf(tree); 
    var item = obj;
    return Squish.createItemName(treeName, item.innerText);
}

An item's name consists of the name of the item view containing the item (the tree widget) and the actual name of the item (usually the item's text—i.e., its innerText—is used).

First we find the tree widget that the item belongs to. This is done by going to the item's parent, and if that isn't the tree, the parent's parent, and so on until we get an object of class gwt-Tree. Once we have located the tree object, we can call the Squish.nameOf() function to get its real (multi-property) name, and then use the Squish.createItemName() function to generate a unique real name for the item; essentially, the same name as the tree's but with an additional property containing the item's text (which we get from the item's innerText).

Now that we have implemented all necessary hook functions we must register them to make them take effect:

Squish.addNameOfHook(gwtExtension.nameOf);
Squish.addTypeOfHook(gwtExtension.typeOf);
Squish.addEventObjectHook(gwtExtension.eventObject);

With these hooks in place, if we now record events on a GWT Tree, the expected high-level operations will be correctly recorded.

	Functions to implement in the view's extension object
	findItem(view, name) itemHandle(item)

Once the recording hooks are implemented and recording works, the next step is to implement the hooks to enable Squish to recognize and correctly replay the recorded GUI operations.

To support replaying clicks on items (clickItem()), only one additional function needs to be implemented. This function has to search for an item by name in the tree, and should return a reference to the DOM object representing the item. Squish will use this function to get the item to send click events to.

The name of this function has to follow a certain naming convention. In particular, it must be called findItem() and it must exist as a function property of an object called typenameExtension where typename is exactly the same name as we appended to the type names of the objects in our typeOf() hook function.

For the GWT Tree example we have typenames custom_item_gwttree and so on, so the name we must use is gwttree. This means that we have to create an object called gwttreeExtension and give it a findItem() function, as the following code illustrates:

var gwttreeExtension = new Object;

gwttreeExtension.findItem = function(tree, itemText)
{
    var node = tree.firstChild;
    
    while (node) {
	if (node.firstChild) {
	    var child = gwttreeExtension.findItem(node, itemText);
	    if (child)
		return child;
	}
	if (node.className && 
	    Squish.hasClassName(node, 'gwt-TreeItem') &&
	    Squish.cleanString(node.innerText) == itemText) {
	    return node;
	}
	node = node.nextSibling;
    }

    return undefined;
}

The tree is a reference to the tree DOM element and the itemText is the item's text (actually its innerText).

The function iterates through all child elements of the tree until it finds an element of class gwt-TreeItem whose innerText matches the requested item text.

For list and table widgets it is sufficient to provide a findItem() function, but for tree widgets an additional function is required to deal with item handles.

For this purpose an itemHandle() function must be implemented in the same object that returns the handle belonging to the given item. Here is an implementation of the function that works for GWT Tree items:

gwttreeExtension.itemHandle = function(node)
{
    return node.parentNode.previousSibling.firstChild;
}

This function returns the GWT Tree element that corresponds to an item handle (an IMG element in the TD element above the item—i.e., the item's parent's previous sibling's first child.)

The implementation of these two functions is all that's needed to enable the replaying of high-level operations on items and item handles.

	Functions to implement in the view's extension object
	itemText(item) isItemSelected(item) isItemOpen(item) setItemSelected(item, selected) setItemOpen(item, open) childItem(itemOrView) parentItem(item) nextSibling(item) itemView(item) numColumns(view) columnCaption(view, column)

For Squish to be able to detect an item view and its items, and be able to record and replay high-level GUI operations involving them, what we have done so far is sufficient.

But Squish's item view abstraction also provides the tester with APIs to iterate through the items and to query and set the selection and other properties. To support such functionality, various additional functions need to be implemented—all of which we will cover here, again providing examples based on the GWT Tree example.

gwttreeExtension.itemText = function(item)
{
    return item.innerText;
}

gwttreeExtension.isItemSelected = function(item)
{
    return Squish.hasClassName(item, "gwt-TreeItem-selected");
}

gwttreeExtension.isItemOpen = function(item)
{
    return gwttreeExtension.itemHandle(item).src.indexOf('tree_open') != -1;
}

gwttreeExtension.childItem = function(node)
{
    if (Squish.hasClassName(node, "gwt-Tree")) {
        return Squish.getElementByClassName(node, 'gwt-TreeItem', 'SPAN');
    } else {
        while (node && node.tagName != 'TABLE')
            node = node.parentNode;
        if (!node || !node.nextSibling)
            return undefined;
        node = node.nextSibling;
        return Squish.getElementByClassName(node, 'gwt-TreeItem', 'SPAN');
    }
}

gwttreeExtension.nextSibling = function(node)
{
    while (node && node.tagName != 'DIV')
        node = node.parentNode;
    if (!node || !node.nextSibling)
        return undefined;
    node = node.nextSibling;
    return Squish.getElementByClassName(node, 'gwt-TreeItem', 'SPAN');
}

gwttreeExtension.parentItem = function(node)
{
    while (node && node.tagName != 'DIV')
        node = node.parentNode;
    if (!node || !node.parentNode || !node.parentNode.previousSibling)
        return undefined;
    node = node.parentNode.previousSibling;
    return Squish.getElementByClassName(node, 'gwt-TreeItem', 'SPAN');
}

gwttreeExtension.itemView = function(node)
{
    while (node && !Squish.hasClassName(node, 'gwt-Tree'))
        node = node.parentNode;
    return node;
}

This concludes the coverage of the JavaScript Extension API. A couple of test scripts which use the GWT Tree APIs developed in this section can be found in the examples/web/suite_gwt suite.