Services registered with register_new_service are available for all users. We call them public services.

Page generation may have side-effects:

let count = 
  let next =
    let c = ref 0 in
      (fun () -> c := !c + 1; !c)
  in
  register_new_service 
    ~path:["count"]
    ~get_params:unit
    (fun _ () () -> 
      return
        (html
         (head (title (pcdata "counter")) [])
         (body [p [pcdata (string_of_int (next ()))]])))

See this example here.

As usual in OCaml, you can forget labels when the application is total:

let hello = 
  register_new_service 
    ["dir";"hello"]  (* the url dir/hello *)
    unit
    (fun _ () () ->
      return
        (html
         (head (title (pcdata "Hello")) [])
         (body [h1 [pcdata "Hello"]])))

See this example here.

Warning about pathes: ["foo";"bar"] is not equivalent to ["foo/bar"]. In the latter, the "/" will be encoded in the URL.

The last example shows how to define the default page for a directory. (Note that ["rep";""] is equivalent to ["rep";"index"], because some browsers do not behave well with empty links.)

let default = register_new_service ["rep";""] unit
  (fun _ () () -> 
    return
     (html
      (head (title (pcdata "")) [])
      (body [p [pcdata "default page. rep is redirected to rep/"]])))

See default.

Typed parameters

The parameter labeled get_params indicates the type of GET parameters for the page (that is, parameters present in the URL). unit means that the page does not take any GET parameter.

Functions implementing services are called service handlers. They take three parameters. The first one has type Eliomsessions.server_params and corresponds to server parameters (user-agent, ip, current-url, etc. - see later in that section for examples of use), the second one is for GET parameters (that is, parameters in the URL) and the third one for POST parameters (parameters in the body of the HTTP request).

Here is an example of a service with GET parameters:

let writeparams _ (i1, (i2, s1)) () =  
  return
   (html
    (head (title (pcdata "")) [])
    (body [p [pcdata "You sent: ";
              strong [pcdata (string_of_int i1)];
              pcdata ", ";
              strong [pcdata (string_of_int i2)];
              pcdata " and ";
              strong [pcdata s1]]]))

let coucou_params = register_new_service 
    ~path:["coucou"]
    ~get_params:(int "i" ** (int "ii" ** string "s"))
    writeparams

Note that the URLs of coucou and coucou_params differ only by parameters. Url http://your_server/examples/coucou will run the first one,
http://your_server/examples/coucou?i=42&ii=17&s=krokodile will run the second one.
If i is not an integer, the server displays an error-message (try to change the value in the URL).
Here, int, string and are functions defined in the Eliomparameters module.
Warning: The infix function ( ) is to be used to construct pairs (not tuples).

The following examples shows how to create a service with "suffix" service (taking the end of the URL as a parameter, as wikis do very often) and how to get server information:

let uasuffix = 
  register_new_service 
    ~path:["uasuffix"]
    ~get_params:(suffix (int "year" ** int "month"))
    (fun sp (year, month) () -> 
      return
       (html
        (head (title (pcdata "")) [])
        (body
           [p [pcdata "The suffix of the url is ";
               strong [pcdata ((string_of_int year)^"/"
                               ^(string_of_int month))];
               pcdata ", your user-agent is ";
               strong [pcdata (Eliomsessions.get_user_agent sp)];
               pcdata ", your IP is ";
               strong [pcdata (Eliomsessions.get_ip sp)]]])))

This service will answer to URLs like http://.../uasuffix/2000/11.

See uasuffix

Suffix parameters have names, because we can create forms towards these services. uasuffix/2000/11 is equivalent to uasuffix/?year=2000&month=11.

suffix_prod allows to take both a suffix and other parameters.
all_suffix allows to take the end of the suffix as string list.

let isuffix = 
  register_new_service 
    ~path:["isuffix"] 
    ~get_params:(suffix_prod (int "suff" ** all_suffix "endsuff") (int "i"))
    (fun sp ((suff, endsuff), i) () -> 
      return
       (html
        (head (title (pcdata "")) [])
        (body
           [p [pcdata "The suffix of the url is ";
               strong [pcdata (string_of_int suff)];
               pcdata " followed by ";
               strong [pcdata (Extensions.string_of_url_path endsuff)];
               pcdata " and i is equal to ";
               strong [pcdata (string_of_int i)]]])))

See isuffix.

The following example shows how to use your own types:

type mysum = A | B
let mysum_of_string = function
  | "A" -> A
  | "B" -> B
  | _ -> raise (Failure "mysum_of_string")
let string_of_mysum = function
  | A -> "A"
  | B -> "B"

let mytype = 
  Eliompredefmod.Xhtml.register_new_service 
    ~path:["mytype"]
    ~get_params:
      (Eliomparameters.user_type mysum_of_string string_of_mysum "valeur")
    (fun _ x () -> 
      let v = string_of_mysum x in 
      return
        (html
         (head (title (pcdata "")) [])
         (body [p [pcdata (v^" is valid. Now try with another value.")]])))

See mytype.

Untyped parameters

If you want a service that answers to request with any parameters, use the Eliomparameters.any value. The service will get an association list of strings. Example:

let raw_serv = register_new_service 
    ~path:["any"]
    ~get_params:Eliomparameters.any
  (fun _ l () ->
    let ll = 
      List.map 
        (fun (a,s) -> << <strong>($str:a$, $str:s$)</strong> >>) l 
    in  
    return
     << <html>
          <head><title></title></head>
          <body>
          <p>
            You sent: 
            $list:ll$
          </p>
          </body>
        </html> >>)

Try raw_serv.

let catch = register_new_service
    ~path:["catch"]
    ~get_params:(int "i")
    ~error_handler:(fun sp l -> 
      return
        (html
         (head (title (pcdata "")) [])
         (body [p [pcdata ("i is not an integer.")]])))
    (fun _ i () -> 
      let v = string_of_int i in 
      return
        (html
           (head (title (pcdata "")) [])
           (body [p [pcdata ("i is an integer: "^v)]])))

To create a link (<a>), use the function Eliompredefmod.Xhtml.a (or Eliomduce.Xhtml.a, etc), as in these examples:

let links = register_new_service ["rep";"links"] unit
 (fun sp () () -> 
   return
    (html
     (head (title (pcdata "Links")) [])
     (body 
       [p
        [Eliompredefmod.Xhtml.a coucou sp [pcdata "coucou"] (); br ();
         Eliompredefmod.Xhtml.a hello sp [pcdata "hello"] (); br ();
         Eliompredefmod.Xhtml.a default sp 
           [pcdata "default page of the dir"] (); br ();
         Eliompredefmod.Xhtml.a uasuffix sp 
           [pcdata "uasuffix"] (2007,06); br ();
         Eliompredefmod.Xhtml.a coucou_params sp 
           [pcdata "coucou_params"] (42,(22,"ciao")); br ();
         Eliompredefmod.Xhtml.a raw_serv sp 
           [pcdata "raw_serv"] [("sun","yellow");("sea","blue and pink")]; br ();
         Eliompredefmod.Xhtml.a
           (new_external_service
              ~prefix:"http://fr.wikipedia.org"
              ~path:["wiki";""]
              ~get_params:(suffix (all_suffix "suff"))
              ~post_params:unit ()) 
           sp
           [pcdata "OCaml on wikipedia"]
           ["OCaml"]; br ();
         XHTML.M.a
           ~a:[a_href (uri_of_string "http://en.wikipedia.org/wiki/OCaml")]
           [pcdata "OCaml on wikipedia"]
       ]])))

See links.

If you open Eliompredefmod.Xhtml after XHTML.M, Eliompredefmod.Xhtml.a will mask XHTML.M.a. Thus you can avoid to write fully qualified values most of the time.

Eliompredefmod.Xhtml.a takes as first parameter the service you want to link to. Note that to create a (relative) link we need to know the current URL. That's why the function a takes sp as second parameter.

The third parameter is the text of the link. The last parameter is for GET parameters you want to put in the link. The type of this parameter and the name of GET parameters depend on the service you link to.

The links to Wikipedia shows how to define an external service (here it uses a suffix URL). For an external service without parameters, you can use the low level function XHTML.M.a, if you don't want to create an external service explicitely. Note that the path must be a list of strings. Do not write ["foo/bar"], but ["foo";"bar"], otherwise, the "/" will be encoded in the URL.

If you want to create (mutually or not) recursive pages, first create the service using Eliomservices.new_service, then register it in the table using (for example) Eliompredefmod.Xhtml.register:

let linkrec = Eliomservices.new_service ["linkrec"] unit ()

let _ = Eliompredefmod.Xhtml.register linkrec 
    (fun sp () () -> 
      return
       (html
        (head (title (pcdata "")) [])
        (body [p [a linkrec sp [pcdata "click"] ()]])))

See linkrec.

The server will fail on start up if there are any unregistered services.

Forms towards services

The function Eliompredefmod.Xhtml.get_form allows to create a form that uses the GET method (parameters in the URL). It works like Eliompredefmod.Xhtml.a but takes as parameter a function that creates the form from parameters names.

let create_form = 
  (fun (number_name, (number2_name, string_name)) ->
    [p [pcdata "Write an int: ";
        Eliompredefmod.Xhtml.int_input ~input_type:`Text ~name:number_name ();
        pcdata "Write another int: ";
        Eliompredefmod.Xhtml.int_input ~input_type:`Text ~name:number2_name ();
        pcdata "Write a string: ";
        Eliompredefmod.Xhtml.string_input ~input_type:`Text ~name:string_name ();
        Eliompredefmod.Xhtml.string_input ~input_type:`Submit ~value:"Click" ()]])

let form = register_new_service ["form"] unit
  (fun sp () () -> 
     let f = Eliompredefmod.Xhtml.get_form coucou_params sp create_form in 
     return
       (html
         (head (title (pcdata "")) [])
         (body [f])))

See the function form in action.

Note that if you want to use typed parameters, you cannot use functions like XHTML.M.input to create your forms (but for parameters defined with Eliomparameters.any, see later). Indeed, parameter names are typed to force them be used properly. In our example, number_name has type int param_name and must be used with int_input (or other widgets), whereas string_name has type string param_name and must be used with string_input (or other widgets). All functions for creating form widgets are detailed here.

For untyped forms, you may use functions from XHTML.M (or OCamlDuce's syntax, or whatever syntax you are using) or functions whose name is prefixed by "raw_". Here is a form linking to our (untyped) service raw_serv.

let raw_form = register_new_service 
    ~path:["anyform"]
    ~get_params:unit
    (fun sp () () ->
      return
        (html
           (head (title (pcdata "")) [])
           (body 
              [h1 [pcdata "Any Form"];
               Eliompredefmod.Xhtml.get_form raw_serv sp 
                 (fun () ->
                   [p [pcdata "Form to raw_serv: ";
                       Eliompredefmod.Xhtml.raw_input ~input_type:`Text ~name:"plop" ();
                       Eliompredefmod.Xhtml.raw_input ~input_type:`Text ~name:"plip" ();
                       Eliompredefmod.Xhtml.raw_input ~input_type:`Text ~name:"plap" ();
                       Eliompredefmod.Xhtml.string_input ~input_type:`Submit ~value:"Click" ()]])
                ])))

Try this form.

POST parameters

By default Web page parameters are passed in the URL (GET parameters). A web page may also expect POST parameters (that is, parameters that are not in the URL but in the body of the HTTP request). Use this if you don't want the user to be able to bookmark the URL with parameters, for example if you want to post some data that will change the state of the server (payment, database changes, etc). When designing a Web site, think carefully about the choice between GET or POST method for each service!

When you register a service with POST parameters, you must register before a service (fallback) without these parameters (for example that will answer if the page is reloaded without the hidden parameters, or if it is bookmarked).

let no_post_param_service = 
  register_new_service 
    ~path:["post"]
    ~get_params:unit
    (fun _ () () -> 
      return
        (html
         (head (title (pcdata "")) [])
         (body [h1 [pcdata 
                      "Version of the page without POST parameters"]])))
    
let my_service_with_post_params = 
  register_new_post_service
    ~fallback:no_post_param_service
    ~post_params:(string "value")
    (fun _ () value -> 
      return
        (html
         (head (title (pcdata "")) [])
         (body [h1 [pcdata value]])))

Services may take both GET and POST parameters:

let get_no_post_param_service = 
  register_new_service 
    ~path:["post2"]
    ~get_params:(int "i")
    (fun _ i () -> 
      return
        (html
         (head (title (pcdata "")) [])
         (body [p [pcdata "No POST parameter, i:";
                   em [pcdata (string_of_int i)]]])))

let my_service_with_get_and_post = register_new_post_service 
  ~fallback:get_no_post_param_service
  ~post_params:(string "value")
  (fun _ i value -> 
    return
      (html
         (head (title (pcdata "")) [])
         (body [p [pcdata "Value: ";
                   em [pcdata value];
                   pcdata ", i: ";
                   em [pcdata (string_of_int i)]]])))

POST forms

To create a POST form, use the Eliompredefmod.Xhtml.post_form function. It is similar to Eliompredefmod.Xhtml.get_form with an additional parameter for the GET parameters you want to put in the URL (if any). Here form2 is a page containing a form to the service post (using XHTML.M's functions) and form3 (defined using the syntax extension) contains a form to post2, with a GET parameter. form4 is a form to an external page.

let form2 = register_new_service ["form2"] unit
  (fun sp () () -> 
     let f =
       (Eliompredefmod.Xhtml.post_form my_service_with_post_params sp
          (fun chaine -> 
            [p [pcdata "Write a string: ";
                string_input ~input_type:`Text ~name:chaine ()]]) ()) in
     return
       (html
         (head (title (pcdata "form")) [])
         (body [f])))

let form3 = register_new_service ["form3"] unit
  (fun sp () () ->
     let f  = 
       (Eliompredefmod.Xhtml.post_form my_service_with_get_and_post sp
          (fun chaine -> 
            <:xmllist< <p> Write a string: 
                    $string_input ~input_type:`Text ~name:chaine ()$ </p> >>)
          222) in 
     return
       << <html>
            <head><title></title></head>
            <body>$f$</body></html> >>)

let form4 = register_new_service ["form4"] unit
  (fun sp () () ->
     let f  = 
       (Eliompredefmod.Xhtml.post_form
          (new_external_service 
             ~prefix:"http://www.petizomverts.com"
             ~path:["zebulon"]
             ~get_params:(int "i")
             ~post_params:(string "chaine") ()) sp
          (fun chaine -> 
            <:xmllist< <p> Write a string: 
                     $string_input ~input_type:`Text ~name:chaine ()$ </p> >>)
          222) in 
     return
       (html
        (head (title (pcdata "form")) [])
        (body [f])))

See the urls: post without parameter, post2 without POST parameter, form2, form3, form4.

Remember that a Web site written with Eliom is an OCaml application. This application must be able to handle several requests at the same time, if one of the requests takes time. To make this possible, Ocsigen is using cooperative threads, implemented in monadic style by Jérôme Vouillon (Lwt module), which make them really easy to use.

Take time to read the documentation about Lwt right now if you want to understand the foloowing of this tutorial.

As it does not cooperate, the following page will stop the server for 5 seconds. No one will be able to do a request during this delay:

let looong =
  register_new_service
    ~path:["looong"]
    ~get_params:unit
    (fun sp () () ->
      Unix.sleep 5;
      return
        (html
          (head (title (pcdata "")) [])
          (body [h1 [pcdata "Ok now, you can read the page."]])))

To solve this problem, use a cooperative version of sleep:

let looong = 
  register_new_service 
    ~path:["looong"]
    ~get_params:unit
    (fun sp () () -> 
      Lwt_unix.sleep 5.0 >>= fun () ->
      return
        (html
          (head (title (pcdata "")) [])
          (body [h1 [pcdata 
                   "Ok now, you can read the page."]])))

If you want to use, say, a database library that is not written in cooperative way, but is thread safe for preemptive threads, use the Preemptive module to detach the computation. In the followinf example, we simulate the request by a call to Unix.sleep:

let looong2 = 
  register_new_service 
    ~path:["looong2"]
    ~get_params:unit
    (fun sp () () -> 
      Preemptive.detach Unix.sleep 5 >>= fun () ->
      return
        (html
          (head (title (pcdata "")) [])
          (body [h1 [pcdata 
                   "Ok now, you can read the page."]])))

See looong2.