As an example lets take a menu element which looks like

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

First, let us register the menu items as clickable widgets with

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

More about that in Support for Simple Widgets (Section 16.14.2)

Now, we want the menuID attribute, the DOM class name and the ID of the parent element to be used in the object name. Therefore we implement a function which generates a name for menuItem SPANs:

var myuiExtension = new Object;

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

We add this function as a property of the myuiExtension object. In the implementation we check if the object is a menu item (which we want to handle). If this is not the case we return undefined so Squish will call the default name generator or any other installed name generation hook.

To check if the element is the one we want to handle we check if its tag name is SPAN and if it is of the DOM class menuItem. For this check we can use the helper function Squish.hasClassName() which checks if any of the specified DOM classes of the object matches the desired one.

In case we decided to handle an object we have to assemble its name. We will return it as string of the format {property1='value1' property2='value2' ... propertyN='valueN'}.

The Squish.propertiesToName() function can be used to conveniently generate a name from properties than can directly be queried from an object. This function expects the object and an array of property names as arguments and returns a string of the format property1='value1' property2='value2' ... propertyN='valueN'.

So we specify the mandatory tagName and the menuID property this way.

Then we add the ID of the parent element as parentID property to the name. As it is not a regular property of the object itself it will be a so-called pseudo-property.

Finally, we add className='menuItem' to the name. We cannot use the Squish.propertiesToName() for in this case since the DOM property name is class while Squish uses the JavaScript className identifier. Also, a DOM class may contain multiple values while we only want to specify menuItem.

After we built the name we make the name unique. We don't have to do this manually but can use the Squish.uniquifyName() function for that which expects the generated name and the actual object which should be identified by the name. This function will, if necessary, add an occurrence property to the name.

To ensure that special characters are escaped properly we use the standard JavaScript escape() function and return the result.

Now we have to let Squish know about this function to be used for name generation:

Squish.addNameOfHook(myuiExtension.nameOf);

As a result the name of the Open menu item will look like {tagName='SPAN' menuID='fileOpen' parentID='fileMenu' className='menuItem'}.

When searching 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.

Using a custom name generator hook it is possible to also add pseudo-properties to a name as we did for the parentID. As Squish has no knowledge about this property we need to implement a function performing the lookup and matching.

myuiExtension.matchObject = function(o, prop, value) {
    if (prop == "parentID")
	return Squish.matchProperty(value, o.parentNode.id);

    return undefined;
}

Again, we implement this function as a property of the myuiExtension object. Squish will pass the object, the property name and the expected value as specified in the name to this function.

In the implementation we will first check whether we want to handle a requested property. If not, we simply return undefined so Squish will try to resolve it through other means.

In our case we decide to handle the parentID property and we do matching ourself and return true or false depending on whether the value matches or not.

The value is not just a string but an object which contains the string value and flags denoting whether the matching should be based on a simple string comparison, a regular expression or wildcards. See ##### on that topic.

The exact details are nothing to worry about, though. The Squish.matchProperty() function can be used to take care of all that. The function expects the value object as the first argument and the string of the property value of the specified object as second argument. In our example we get the string value by querying the id of the specified object's parent DOM node.

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

Squish.addMatchObjectHook(myuiExtension.matchObject);

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

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

The respective DOM hierarchy representing this tree widget has the following structure (simplified to only display relevant details):

<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 gwt-Tree.

An item in the tree is contained in a TABLE inside a DIV element. The actual item is a SPAN element of the class gwt-TreeItem. The item text is the inner text of this element. If an item is selected, its class name also contains gwt-TreeItem-selected.

The item handle (the + or - symbol in front of the item) is represented by an IMG element in the TD element above (it's the item's parent's previous sibling's first child). Using the src property of the IMG it is possible to find out if the item is expanded (src=tree_open.gif) or collapsed src=tree_closed.gif).

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

Using this information it is possible to detect a GWT tree and its items and handles in the DOM structure of a web page.

	Note
	Function 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 an tree item's handle should be recorded as clickTreeHandle("<treename>", "<itemname>").

For this, we need to implement three different hooks:

Once we implemented these function we need to register them with Squish so our functions will be called from the event recorder. When Squish calls them, it will pass the DOM source object of the event as an argument. Based on that we decide whether we will react or not.

In the implementations of these functions we will handle three different high-level objects:

So for all three functions we need a way to determine the high-level type. First we declare constants for the types we handle. We will define all extension functions and constants in our own extension object gwtExtension. This way all the toolkit's extension code will be cleanly encapsulatd in its own object:

var gwtExtension = new Object;

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

Now we implement a function which returns the high-level type for a specified DOM object:

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

    return undefined;
}

Using that function it is quite simple to implement the three mentioned hook functions:

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

    switch (gwtExtension.getType(o)) {
    case gwtExtension.TreeItem:
    case gwtExtension.TreeItemHandle:
	return o;
    }

    return undefined;
}

If the high-level object type is a tree item or handle, we return this object. This tells Squish that this is an object we want to record events on and which should not be ignored by the event recorder.

If Squish comes across such an object which events should be recorded on, it will need to find out the type of this object. For that we implement the next hook:

gwtExtension.typeOf = function (o)
{
    switch (gwtExtension.getType(o)) {
    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 which needs to be adhered to. Squish provides a common item view abstraction. Such an item view consists of three main components. To denote which of the components the DOM object represents, the returned type name has to start with a defined prefix:

Following the defined prefix we need to add the specific type name which we use for the item view which we support. In our case this is gwttree.

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

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

In this function we use the functions gwtExtension.nameOfTree() and gwtExtension.nameOfTreeItem() to create names for the respective objects. Here are the implementations:

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

This function creates a unique name for the tree object. More about how names are built can be read in Implementing a Custom Name Generator (Section 16.14.3.1).

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

gwtExtension.nameOfTreeItem = function (o)
{
    var tree = o;
    while (tree && (!Squish.hasClassName(tree, 'gwt-Tree')))
	tree = tree.parentNode;
    var treeName = Squish.nameOf(tree); 

    var item = o;

    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 (innerText) is used).

So first we have to determine the tree widget. This can be done by walking up the parents until we get an object of class gwt-Tree. Once we have located the tree object, we can call Squish.nameOf() to get its name.

For the item's name we use its innerText.

To build a name in the correct format, we can use the convenience function Squish.createItemName() which expects the name of the item view's (tree) as first argument and the item's name as second argument.

Now that we have implemented all necessary hook functions we need to register them:

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

If we now record events on a GWT tree, the expected high-level operations will be recorded.

	Note
	Function 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 the automated script replay of the recorded GUI operations.

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

The name of this function needs to follow a certain naming convention. The function has to be called findItem and it has to exist in an object of the name <type>Extension. <type> is exactly what we appended to the type names of the objects in our typeOf() hook function. So in our case this is gwttree which means that we need to implement a function called gwttreeExtension.findItem which takes a reference to the DOM object representing the tree and the name of the requested item as arguments:

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

    return undefined;
}

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.

The other available function is required if items have handles to expand and collapse an item. Therefore this function is only necessary when implementing support for a tree widget.

For this purpose a itemHandle() function needs to be implemented in the same object which returns the handle belonging to the given item. For GWT tree items this looks like this:

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

That's already all that is needed to enable replaying of high-level operations on items and item handles.

	Note
	Function 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)

To allow Squish to properly detect an item view and its items to be able to record and replay high-level GUI operations, nothing more is needed. But Squish's item view abstraction also provides the tester with APIs to iterate through the items and query and set the selection and other properties. To allow that, some more functions need to be implemented which will be discussed in this section.

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

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

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

gwttreeExtension.childItem = function (parent)
{
    if (Squish.hasClassName(parent, "gwt-Tree")) {
	return Squish.getElementByClassName(parent, 'gwt-TreeItem', 'SPAN');
    } else {
	while (parent && parent.tagName != 'TABLE')
	    parent = parent.parentNode;
	if (!parent || !parent.nextSibling)
	    return undefined;
	parent = parent.nextSibling;
	return Squish.getElementByClassName(parent, '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)
{
    var t = node;
    while (t && (!Squish.hasClassName(t, 'gwt-Tree')))
	t = t.parentNode;
    return t;
}

This concludes this section. A few tests scripts which use the provided high-level API and item view abstractions on a GWT tree widget can be found in examples/web/suite_gwt.