setFrameContext

Boolean setFrameContext(browserTab, frameName)

Boolean setFrameContext(frameName)

For web pages that use frames or iframes, this function can be used to specify that the frame called frameName should be used as the current context when looking up objects inside the tab referenced by browserTab. This current context defines the preferred window to look up object names and thus all object lookups that follow it will first search for the object in the specified frame. If no object is found the lookup will fall back to search through all other frames as well as the top level page. The frameName uses a dot-separated hierarchy identifying the wanted frame. The name starts with the top-most frame in the webpage, using either the name attribute of that frame or the id attribute. The next step (if necessary) should be the name or id of a frame inside the top-most frame. Continuing this scheme any level of nested frames can be reached. As an example, consider a page which has two frames in it named leftframe and rightframe and the left frame has an iframe inside it with the id maincontent. In order to set the lookup context to this inner iframe you'd use "leftframe.maincontent" as frameName. In addition to this scheme its also possible to use the context information that Squish generates in multi-property and hierarchical names. This context information uses a slightly different format where the name of the frame is the word FRAME followed by a number. The number indicates the number of the given frame in the list of frames in a particular page starting to count at one. Using the example above again, you could use "FRAME1.FRAME1" as name for the iframe inside the left frame. In case the right frame has 2 sub frames itself you would use "FRAME2.FRAME1" and "FRAME2.FRAME2" to access these two sub frames respectively in this scheme. (See also, HTML_Array contextList(), String currentContext(), Boolean setContext(context), and waitForContextExists(context).)

This function throws a catchable script error if the context name cannot be found. You can change this behavior using the ThrowErrorOnUnknownContextNames setting in the file etc/webwrapper.ini. If the setting is set to false this function simply returns true if the given frame context name could be found and activated and false otherwise.