(* How to format the control section. *)
type formatCtl = {Width : int,
                  (* Maximum number of page options to show. *)
                  RangeCtl : $(mapU (transaction {} -> xbody) [First, Back, Next, Last]),
                  (* A group of four functions taking transactions which will be used to return
                   * an element having that transaction as onclick.  Used to format the buttons
                   * controlling the selection of page options.  First starts the options at the
                   * first page, Back starts the options one page lower, Next one page higher
                   * and Last has them finish at the final page. *)
                  PageCtl :  $(mapU (int -> transaction {} -> xbody) [Unsel, Sel]),
                  (* Used to generate the xml bearing the page selection onclick action. Sel
                   * is used for the currently shown page and Unsel for the others. *)
                  WrapPageCtl : xbody -> xbody,
                  (* The sequence of page selection controls will be wrapped by this. *)
                  Wrap : $(mapU xbody [First, Back, Pages, Next, Last]) -> xbody
                  (* Draws the control by placing the individual controls in the holes. *)}

style firstCtl
style backCtl
style nextCtl
style lastCtl
style curPage
style rangeCtl
(* Default styles. *)

val defaultFormat : formatCtl
(* A reasonable default format. *)

val defaultFormatLbl : $(mapU string [First, Back, Next, Last]) -> formatCtl
(* A default format with configurable labels on the page range controls. *)

type pageData = {Content : xbody, Available : int}
(* Content and page count needed from the RPC. *)

datatype response err = Good of pageData | Bad of err
(* The RPC gives us either page information or an error code. *)

functor Make(M : sig
                 type errorMarker
                 (* Classifies the possible error conditions returned by the rpc call. *)

                 type pageGroup
                 (* Classifies families of pages. *)

                 val initPage : pageGroup -> transaction pageData
                 (* Used once to initialize the first page and page count.
                  * The RPC mechanism is not used and no error is possible. *)

                 val getPage : pageGroup -> int -> transaction (response errorMarker)
                 (* RPC giving the content of a requested page as well as the count
                  * of how many pages are available.  The first page should be given
                  * an index of 0. *)
             end) : sig

    type t
    (* The type of remote pagers.  A remote pager is a
     * widget which shows a list of available "pages" of
     * information.  The user can click on a page they want
     * displayed, which is then fetched from the server via
     * a RPC. *)

    val createFmt : formatCtl -> M.pageGroup -> transaction t
    (* Get a remote pager widget with a custom format showing pages from the selected group. *)

    val create : M.pageGroup -> transaction t
    (* Get a remote pager widget with the default format (partly customizable via CSS). *)

    val onError : t -> (M.errorMarker -> transaction {}) -> transaction {}
    (* Allows setting an error handler.  In case of an rpc error code return, this will
     * be called with the received error marker.  If not set, the default error handler
     * does nothing. *)

    val panelXml : t -> xbody
    (* Returns a piece of xml holding the contents of the current page. *)

    val ctlXml : t -> xbody
    (* Returns a xml widget representing the clickable page selection controls. *)
end