#reader(lib "docreader.ss" "scribble")

@require[(file "base.ss")]

@title[#:tag "browser"]{Browser API}

The Delirium browser API is provided by the main @file{delirium.ss} which
you can require as follows:

@schemeblock[
  (require (planet "delirium.ss" ("untyped" "delirium.plt" 1)))]

The procedures in the browser API are organised into three modules as
follows:

@itemize{

  @item{@italic{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, @scheme[node/id]
    selects an HTML element by its ID attribute.}
 
  @item{@italic{Accessors} query some aspect of the browser or current 
    page and return it to the server. For example, @scheme[title-ref]
    retrieves the value of the @var{<title>} element of the current 
    page.}

  @item{@italic{Commands} tell the browser to perform an action such as
    clicking a link or typing in a URL. For example, @scheme[type] 
    enters text into a text field or text area.}}
    
In addition to being provided through @file{delirium.ss}, each module 
may be required separately:

@schemeblock[
  (require (planet "selector.ss" ("untyped" "delirium.plt" 1))
           (planet "accessor.ss" ("untyped" "delirium.plt" 1))
           (planet "command.ss"  ("untyped" "delirium.plt" 1)))]

@section{Javascript representations}

First, a brief aside on Javascript representations. Delirium sends
commands to the client as Javascript thunks. These thunks are assembled
using the AST structures from Dave Herman's 
@link[url:dherman/javascript.plt]{javascript.plt} package.

Delirium takes care of all of this internally. The internal workings are
only exposed through contracts on the arguments and return values on
selectors, accessors and commands:

@defproc*[([(javascript-expression? [item any])
            boolean?]
           [(javascript-statement? [item any])
            boolean?])]

@section{Selectors}

Selectors create Javascript fragments that, when executed in the browser,
select @italic{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 you want to 
search.

@defproc[(node/document) javascript-expression?]

Selects the @italic{document element} of the current page. Equivalent to
selecting the @scheme[document] object in Javascript.

@defproc[(node/id [relative-to javascript-expression? (node/document)]
                  [id (U string? symbol?)])
         javascript-expression?]{
  Selects an element by its @scheme[id] attribute. Equivalent to using
  @scheme[document.getElementById] in Javascript.}

@defproc[(node/tag [relative-to javascript-expression? (node/document)]
                   [tag-name (U string? symbol?)])
         javascript-expression?]{
  Selects elements by their tag name. Equivalent to using
  @scheme[element.getElementsByTag] in Javascript.}

@defproc[(node/xpath [relative-to javascript-expression? (node/document)]
                     [xpath string?])
         javascript-expression?]{
  Selects nodes using an @link["http://www.w3.org/TR/xpath"]{XPath}
  query string.}

@defproc[(node/link/text [relative-to javascript-expression? (node/document)]
                         [text string?])
         javascript-expression?]{
  Selects links that @italic{contain} the specified @scheme[text] 
  (doesn't have to be a complete match).}

@section{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:

@defproc[(title-ref)
         string?]{
  Returns the value of the @scheme[<title>] element of the current page.}

@section{Commands}

Commands tell the browser to perform an action. Examples include entering
form data or typing in a URL:

@defproc[(open/wait [url (U string? (-> request? response?))])
         void?]{
  Opens the specified @scheme[url] in the browser and waits for the page
  to refresh. The check fails if an exception is thrown in the Javascript 
  code.}

@defproc[(click*/wait [selector javascript-expression?])
         void?]{
  Clicks the elements returned by the @scheme[selector] and waits for the
  page to refresh. Raises @scheme[exn:fail:delirium:browser] if no 
  elements are found.}

@defproc[(click/wait [selector javascript-expression?])
         void?]{
  As @scheme[click*/wait], but only clicks the first element returned by
  the @scheme[selector].}

@defproc[(click* [selector javascript-expression?])
         void?]{
  Clicks the elements (hyperlinks, checkboxes or buttons) returned by the
  @scheme[selector]. Raises @scheme[exn:fail:delirium:browser] if no 
  elements are found, or if any element is not clickable.}

@defproc[(click [selector javascript-expression?])
         void?]{
  As @scheme[click*], but only clicks the first element returned by the
  @scheme[selector].}

@defproc[(select* [selector javascript-expression?]
                  [value (U string? symbol?)])
         void?]{
  Selects a value in the elements (combo boxes, radio buttons) returned
  by @scheme[selector]. The @scheme[value] argument refers to the 
  @italic{value} attributes of the control. For example:

  @verbatim[#<<ENDHTML
  <select name="name">
    <option value="value1">Text</option>
    <option value="value2">Text</option>
    <option value="value3">Text</option>
  </select>
ENDHTML
    ]

  Raises @scheme[exn:fail:delirium:browser] if no elements are selected 
  or the @scheme[value] is not found in any element.}

@defproc[(select [selector javascript-expression?]
                 [text string?])
         void?]{
  As @scheme[select*] but only selects a value in the first element
  returned by @scheme[selector].}

@defproc[(type* [selector javascript-expression?]
                [text string?])
         void?]{
  Types some @scheme[text] into the elements (text fields, text areas)
  returned by @scheme[selector]. Raises @scheme[exn:fail:delirium:browser]
  if no elements are selected.} 

@defproc[(type [selector javascript-expression?]
               [text string?])
         void?]{
  As @scheme[type*] but only types a value into the first element returned
  by @scheme[selector].}