Sending files ¶

You may want to register a service that will send files. To do that, use the Eliom_output.​Files module. Example:

let sendfile =
  Files.register_service
    ~path:["sendfile"]
    ~get_params:unit
    (fun () () -> return "filename")

Other example, with "suffix" services (see here):

let sendfile2 =
  Files.register_service
    ~path:["files"]
    ~get_params:(suffix (all_suffix "filename"))
    (fun s () ->
      return ("//path//"^(Ocsigen_lib.string_of_url_path ~encode:false s)))

The extension Staticmod is another way to handle static files.

Sending portions of pages

The Eliom_output.​Flow5 and Eliom_output.​Blocks modules allow you to register services that send portions of pages, of any "block" type for HTML5.M (resp. XHTML.M). It is sometimes useful to create AJAX pages (i.e. pages using the XMLHttpRequest Javascript object). Note that the service returns a list of blocks. For sending HTML to client side eliom application, Eliom_output.​Caml is better suited.

let divpage =
  Eliom_output.Blocks.register_service
    ~path:["div"]
    ~get_params:unit
    (fun () () ->
      Lwt.return
        [div [h2 [pcdata "Hallo"];
              p [pcdata "Blablablabla"] ]])

The Eliom_output.​Make_TypedXML_Registration module allows to create other modules for registering portions of pages of other types. For example, Eliom_output.​Flow5 is defined by:

module Flow5 = Make_TypedXML_Registration(XML)(HTML5.M)(struct
  type content = HTML5_types.body_content
end)

Redirections ¶

let redir1 = Eliom_output.Redirection.register_service
    ~options:`Temporary
    ~path:["redir"]
    ~get_params:Eliom_parameters.unit
   (fun () () -> Lwt.return coucou)

let redir = Eliom_output.Redirection.register_service
   ~options:`Temporary
   ~path:["redir"]
   ~get_params:(int "o")
   (fun o () ->
      Lwt.return
        (Eliom_services.preapply coucou_params (o,(22,"ee"))))

Actions ¶

Actions are used to perform sides effects before generating the fallback of a service. When an action is called, the service handler is executed, then the service handler of the fallback service is executed.

Eliom references of scope Eliom_common.​request set in an action handler are still available in the service handler of the fallback.

services that do not generate any page. Use them to perform an effect on the server (connection/disconnection of a user, adding something in a shopping basket, deleting a message in a forum, etc.).

By default, the page you link to is displayed after the action. For example, when you have the same form (or link) on several pages (e.g. a connection form), instead of making a version with post params of all these pages, you can use a single action, registered on a non-attached coservice.

See more details and an example in the section about non-attached coservices below, or in section * * connection-of-user.

The return type of action handlers is unit Lwt.t. We will see later how to transmit information to the service that will take charge of the generation of the page.

A common use of actions and non-attached coservices working together is the implementation of login/logout forms. An example is given in the chapter about the server-side state of the application (section sec-state-connect). In that example, actions and non-attached coservices make staightforward the implementation of the behaviour you generally want for such features:

• Connection and disconnection stay on the same page,
• If you want a connection/disconnection form on each page, no need to create a version with POST parameters of each service.

The implementation of the same behaviour with usual Web programming techniques is usually much more complicated.

Registering services that decide what they want to send ¶

You may want to register a service that will send, for instance, sometimes an XHTML page, sometimes a file, sometimes something else. To do that, use the Eliom_output.​Any module, together with the send function of the module you want to use. Example:

let send_any =
  Eliom_output.Any.register_service
    ~path:["sendany"]
    ~get_params:(string "type")
   (fun s () ->
     if s = "valid"
     then
       Eliom_output.Html5.send
         (html
            (head (title (pcdata "")) [])
            (body [p [pcdata
                        "This page has been statically typechecked.
                         If you change the parameter in the URL you will
                         get an unchecked text page"]]))
     else
       Eliom_output.HtmlText.send
         "<html><body><p>It is not a valid page. Put type="valid" in the
          URL to get a typechecked page.</p></body></html>"
   )

let change_option =
  Eliom_output.Any.register_service
    ~path:["change_option"]
    ~get_params:(unit)
   (fun () () ->
     Eliom_output.Html5.send
       ~code:403
       (html
          (head (title (pcdata "forbidden")) [])
          (body [p [pcdata "forbidden"]])))

let file_or_application =
  Eliom_output.Any.register_service
    ~path:["file_or_application"]
    ~get_params:(string "filename")
   (fun filename () ->
     if Eliom_output.Files.check_file filename
     then
       Eliom_output.appl_self_redirect Eliom_output.Files.send filename
     else
       My_application.send ~code:404
         (html
           (head (title (pcdata "no page")) [])
           (body [p ~a:[a_onclick {{ do some client action }}]
	     [pcdata "the file does not exist"]])))

By customizing an existing registration module ¶

Using Eliom_output.​Customize you can specialise a registration function to avoid code duplication. You can for instance for each service add parameters before calling the service handler, or modify the answer.

A classical use is to check wether a user is logged in before serving the content of a page. That way, we don't need to do the check in every service handler and we can get directly the user informations.

In this example, we check if we are in a session group telling that the user is connected. If it not the case, we generate a login page. When we are in a group, we retrieve the user informations and pass it to the service handler. It returns a title and the content of the body. That way, it also always generate the same css without code duplication.

module Connected_param =
struct
  type page = user_informations -> Eliom_output.Html5.page Lwt.t
  let translate page =
    match Eliom_state.get_volatile_data_session_group
      ~scope:Eliom_common.session () with
	| None -> login_page ()
	| Some group_name ->
	  lwt user_info = get_user_info group_name in
	  lwt (page_title,content) = page user_info in
	  return (html (head (title (pcdata page_title))
	                 [ Some css and things like that ])
	               (body content))
end

module Connected =
  Eliom_output.Customize ( Eliom_output.Html5 ) ( Connected_param )

By building the HTTP frame

When you need to declare some kind of specific service, you may need to create your own registration module: For instance here we define a module serving integers as text. Notice that in that case you can and should use customize instead.

For that you need to use the Eliom_mkreg.​MakeRegister functor.

module Int_reg_base = struct

  type page = int

  type options = unit

  type return = http_service

  type result = (browser_content, http_service) kind

  let result_of_http_result = Eliom_output.cast_http_result

  let send_appl_content = Eliom_services.XNever

  let send ?options ?charset ?code ?content_type ?headers content =
    let content = string_of_int content in
    lwt r = Ocsigen_senders.Text_content.result_of_content content in
    Lwt.return
      { r with
        Ocsigen_http_frame.
        res_code    = code_of_code_option code;
        res_charset = (match charset with
          | None ->  Some (Eliom_config.get_config_default_charset ())
          | _ -> charset);
        res_content_type = (match content_type with
          | None -> r.Ocsigen_http_frame.res_content_type
          | _ -> content_type
        );
        res_headers = (match headers with
          | None -> r.Ocsigen_http_frame.res_headers
          | Some headers ->
            Http_headers.with_defaults headers r.Ocsigen_http_frame.res_headers
        );
      }

end

module Int = Eliom_mkreg.MakeRegister(Int_reg_base)

If your page type has parameters you should use Eliom_mkreg.​MakeRegister_AlphaReturn instead.