3 Browser API
The browser API is used to tell the web browser to do things. Procedures in the API fall into three categories:
Selectors access nodes on the current page. Selectors are used in conjunction with commands and accessors to specify the bits of the page with which you wish to interact. For example, node/id selects an HTML element by its ID attribute.
Accessors query some aspect of the browser or current page and return it to the server. For example, title-ref retrieves the value of the <title> element of the current page.
Commands tell the browser to perform an action such as clicking a link or typing in a URL. For example, type enters text into a text field or text area.
These types of procedure are defined in three modules, each of which is documented separately below. All three of these modules are required and reprovided by "delirium.ss", so you shouldn’t normally need to require them directly in your code.
3.1 Javascript representations
An aside regarding Javascript representations. Delirium sends commands to the client as blocks of Javascript, which are eval’d by a client-side Javascript harness. Delirium uses the Javascript representation from Mirrors.plt, which is in turn based on the AST structures from Dave Herman’s Javascript.plt.
Delirium takes care of most of this Javascript stuff internally. The internal workings are only exposed through contracts on the arguments and return values of the procedures in the API:
| (javascript-expression? item) → boolean? |
| item : any |
| (javascript-statement? item) → boolean? |
| item : any |
The js-ref accessor is the only procedure which requires the programmer to have knowledge of Mirrors’ Javascript language.
3.2 Selectors
Selectors create Javascript fragments that, when executed in the browser,
select arrays of nodes from the page.
On the browser side, all selectors return arrays of nodes: even those that cannot select more than one node. This allows selectors to be nested. Most selectors can take another selector as an optional first argument, allowing you to specify the part(s) of the page that you want to search.
Selects the document element of the current page. Equivalent to
selecting the document object in Javascript.
| (node/id id [relative-to]) → javascript-expression? |
| id : (U string? symbol?) |
| relative-to : javascript-expression? = (node/document) |
Selects an element by its id attribute. Equivalent to using document.getElementById in Javascript.
| (node/tag tag-name [relative-to]) → javascript-expression? |
| tag-name : (U string? symbol?) |
| relative-to : javascript-expression? = (node/document) |
Selects elements by their tag name. Equivalent to using element.getElementsByTagName in Javascript.
| (node/class class-name [relative-to]) → javascript-expression? |
| class-name : (U string? symbol?) |
| relative-to : javascript-expression? = (node/document) |
Selects elements by their CSS class. Elements with multiple CSS classes are returned if one of them is class-name. Equivalent to using document.getElementsByClassName in Prototype.
| (node/xpath xpath [relative-to]) → javascript-expression? |
| xpath : string? |
| relative-to : javascript-expression? = (node/document) |
Selects nodes using an XPath query string.
| (node/jquery query [relative-to]) → javascript-expression? |
| query : string? |
| relative-to : javascript-expression? = (node/document) |
Select nodes using a jQuery string.
| (node/link/text text [relative-to]) → javascript-expression? |
| text : string? |
| relative-to : javascript-expression? = (node/document) |
Selects links that contain the specified text. text can appear anywhere in the text of the link: it doesn’t have to be a complete match.
| (node/cell/xy x y table) → javascript-expression? |
| x : natural? |
| y : natural? |
| table : javascript-expression? |
Selects the cell(s) (<td> or <th>) at position x,y in the specified table(s).
Selects the first node of the selected nodes.
Selects the parents of the selected nodes.
| (node-count selected) → integer? |
| selected : javascript-expression? |
Returns the number of selected nodes.
| (node-exists? selected) → boolean? |
| selected : javascript-expression? |
Returns #t if one or more nodes were selected.
SchemeUnit check that passes if one or more nodes were selected.
| (check-not-found selected [message]) → void? |
| selected : javascript-expression? |
| message : string? = "" |
SchemeUnit check that passes if no nodes were selected.
3.3 Accessors
Accessors query parts of the current page in the browser and return
their values as Scheme literals. Delirium defines the following built-in
accessors:
| (title-ref) → string? |
Returns the value of the <title> element of the current page.
| (inner-html-ref selected) → (U string? #f) |
| selected : javascript-expression? |
Returns the concatenated innerHTML properties of the selected nodes, or #f if no nodes were selected.
| (inner-html-ref* selected) → (listof string?) |
| selected : javascript-expression? |
Returns a list of the innerHTML properties of the selected nodes.
Returns the result of evaluating the specified Javascript expression in the browser window. Results are serialized as JSON and deserialized using Dave Herman’s JSON.plt package. Raises exn:fail:delirium:browser if expr throws a Javascript exception.
| (xpath-path-ref selected) → (U string? #f) |
| selected : javascript-expression? |
Returns an XPath path that can be used as a reference for the first selected node. Useful for remembering the location of a node for repeated selection. Returns #f if no nodes were selected.
The path is assembled from the tag names and indices of each element between the selected node and the nearest absolutely identifiable ancestor node. Absolutely identifiable nodes include the document root and elements with IDs. For example:
"/div[@id='student-data']/table/tbody/tr[4]/td[3]"
| (xpath-path-ref* selected) → (listof string?) |
| selected : javascript-expression? |
Like xpath-path-ref, but returns a list of XPath paths, one for each selected node.
3.4 Commands
Commands simulate the actions of a user in the web browser:
Opens the specified url in the browser. Waits for the page to finish reloading before returning.
| (reload/wait) → void? |
Simulates the user reloading or refreshing the page. Waits for the page to finish reloading before returning.
| (back/wait) → void? |
Simulates the user clicking the "Back" button. While some browsers avoid reloading pages in the history if they are cached, back/wait always causes the page to be reloaded from the server. Waits for the page to finish reloading before returning.
| (forward/wait) → void? |
Simulates the user clicking the "Back" button. While some browsers avoid reloading pages in the history if they are cached, forward/wait always causes the page to be reloaded from the server. Waits for the page to finish reloading before returning.
| (click selected) → void? |
| selected : javascript-expression? |
Similates clicking on the first selected node.
| (click* selected) → void? |
| selected : javascript-expression? |
Like click but simulates clicking on all selected nodes.
| (click/wait selector) → void? |
| selector : javascript-expression? |
Like click but waits for the page to refresh after the command has been performed. Raises exn:fail:delirium:browser if the selection does not contain exactly one node.
Simulates selecting value in the first selected <select> input (where text is the value of the "<option>", not the human-friendly text). Raises exn:fail:delirium:browser if no elements are selected, if the first node is not a <select>, or if value is not a valid <option>.
Like select but simulates selecting value in every selected element. Raises exn:fail:delirium:browser if no elements are selected, if one of the nodes node is not a <select>, or if value is not a valid <option> for one of the nodes.
Like select but waits for the page to refresh after the command has been performed. Raises exn:fail:delirium:browser if the selection does not contain exactly one node, if the wrong type of node is selected, or if value is not a valid <option>.
Simulates typing text into the first selected <input> or <textarea>. Raises exn:fail:delirium:browser if the wrong type of node is selected.
Like enter-text but simulates typing text into all the selected nodes instead of just the first. Raises exn:fail:delirium:browser if the wrong type of node is selected.
Like enter-text but waits for the page to refresh after the command has been performed. Raises exn:fail:delirium:browser if the selection does not contain exactly one node or if the wrong type of node is selected.