Previous  Up  Next

Module Eliom_service

module Eliom_service: sig .. end
Creation and manipulation of Eliom services.

See the Eliom manual for a detailed introduction to the concept of .



Type definitions for services



Services kind



Internal or external


type servcoserv = [ `Coservice | `Service ]
An internal attached service could either be a `Service or a `Coservice.
type attached_service_kind = [ `External | `Internal of servcoserv ]
An attached service could either be an `Internal Eliom service or an abstraction for an `External service.

POST or GET parameters


type getpost = [ `Get | `Post ]
The kind of a service is `Post when there is at least one POST parameters. It is `Get otherwise.

Attached or Non-attached


type (+'a, +'b) a_s
The abstract type for attached service representation. 
type +'a na_s
The abstract type for non-attached service representation. 
type service_kind = [ `Attached of
           (attached_service_kind, getpost)
           a_s
       | `Nonattached of getpost na_s ]
The type service_kind describe all four kind of services:

Common subtypes of service_kind 


type get_service_kind = [ `Attached of
           (attached_service_kind, [ `Get ]) a_s
       | `Nonattached of [ `Get ] na_s ]
Restriction of service_kind to services without POST parameters.
type post_service_kind = [ `Attached of
           (attached_service_kind, [ `Post ]) a_s
       | `Nonattached of [ `Post ] na_s ]
Restriction of service_kind to services with at least one POST parameters.
type attached = [ `Attached of
           (attached_service_kind, getpost)
           a_s ]
Restriction of service_kind to attached services.
type nonattached = [ `Nonattached of getpost na_s ]
Restriction of service_kind to non-attached services.
type internal_service_kind = [ `Attached of
           ([ `Internal of servcoserv ], getpost)
           a_s
       | `Nonattached of getpost na_s ]
Restriction of service_kind to internal services.

Kind of parameters


type suff = [ `WithSuffix | `WithoutSuffix ]
The kind of parameters for a service is `WithSuffix when it have a suffix parameter, for examples Eliom_parameter.suffix or Eliom_parameter.suffix_prod. Otherwise it is `WithoutSuffix.

Registrable service


type registrable = [ `Registrable | `Unregistrable ]
A service is `Registrable only if it isn't a pre-applied service, see Eliom_service.preapply.

Abstract type of services


type ('a, 'b, +'c, +[< suff ], +'e, +'f
       , +[< registrable ], +'h) service
Type of services.

Registration of named modules

This functionality allows one to register initialization functions for Eliom modules which will be executed when the corresponding module is loaded in ocsigenserver.conf.

val register_eliom_module : string -> (unit -> unit) -> unit
The function register_eliom_module mod f is used to register the initialization function f to be executed when then module mod is "loaded" by Ocsigen server. The module mod could either be a dynamically loaded module or linked statically into the server: in each case, the f function will be invoked when the module is initialized in the configuration file using <eliom name="name"> ... </eliom>. If register_eliom_module is called twice with the same module name, the second initialization function will replace the previous one.

Definitions of services

Warning: These functions must be called when the site information is available, that is, either during a request or during the initialisation phase of the site. Otherwise, it will raise the exception Eliom_common.Eliom_site_information_not_available. If you are using static linking, you must delay the call to this function until the configuration file is read, using Eliom_service.register_eliom_module. Otherwise you will also get this exception.

Main services


val service : ?https:bool ->
       path:Eliom_lib.Url.path ->
       ?keep_nl_params:[ `All | `None | `Persistent ] ->
       ?priority:int ->
       get_params:('get, [< suff ] as 'a, 'gn)
                  Eliom_parameter.params_type ->
       unit ->
       ('get, unit,
        [> `Attached of
             ([> `Internal of [> `Service ] ], [> `Get ]) a_s ],
        'a, 'gn, unit, [< registrable > `Registrable ], 'return)
       service
The function service ~path ~get_params () creates a Eliom_service.service associated to the path path and taking get_params as GET parameters.

If the optional parameter ~https:true is given, all links towards that service will use https. By default, links will keep the current protocol.

The optional parameter ~priority allows one to change the priority order between service that shares the same path. The default priority is 0 ; if you want the service to be tried before (resp. after) other services, put a higher (resp. lower) priority.

If the optional parameter ~keep_nl_params:`Persistent (resp. ~keep_nl_params:`All) is given, all links towards that service will keep persistent (resp. all) non localized GET parameters of the current service. The default is `None. See the eliom manual for more information about .

val external_service : prefix:string ->
       path:Eliom_lib.Url.path ->
       ?keep_nl_params:[ `All | `None | `Persistent ] ->
       get_params:('get, [< suff ] as 'a, 'gn)
                  Eliom_parameter.params_type ->
       unit ->
       ('get, unit, [> `Attached of ([> `External ], [> `Get ]) a_s ],
        'a, 'gn, unit, [< registrable > `Unregistrable ], 'return)
       service
The function external_service ~prefix ~path ~get_params () creates a service for an external web site, that will use GET method and requires get_params as parameters. This allows one to creates links or forms towards other Web sites using Eliom's syntax.

The parameter labelled ~path is the URL path. Each element of the list will be URL-encoded.

The parameter labelled ~prefix contains all what you want to put before the path. It usually starts with "http://" plus the name of the server. The prefix is not URL encoded.

The whole URL is constructed from the prefix, the path and GET parameters. Hence, an empty prefix can be used to make a link to another site of the same server.

See Eliom_service.service for a description of the optional ~keep_nl_params parameter.

val external_post_service : prefix:string ->
       path:Eliom_lib.Url.path ->
       ?keep_nl_params:[ `All | `None | `Persistent ] ->
       get_params:('get, [< suff ] as 'a, 'gn)
                  Eliom_parameter.params_type ->
       post_params:('post, [ `WithoutSuffix ], 'pn) Eliom_parameter.params_type ->
       unit ->
       ('get, 'post,
        [> `Attached of ([> `External ], [> `Post ]) a_s ], 'a, 'gn,
        'pn, [< registrable > `Unregistrable ], 'return)
       service
Same as Eliom_service.external_service but with POST method.
val post_service : ?https:bool ->
       fallback:('get, unit,
                 [ `Attached of
                     ([ `Internal of [ `Coservice | `Service ] ], [ `Get ])
                     a_s ],
                 [< suff ] as 'a, 'gn, unit, [< `Registrable ],
                 'return1)
                service ->
       ?keep_nl_params:[ `All | `None | `Persistent ] ->
       ?priority:int ->
       post_params:('post, [ `WithoutSuffix ], 'pn) Eliom_parameter.params_type ->
       unit ->
       ('get, 'post,
        [> `Attached of
             ([> `Internal of [ `Coservice | `Service ] ], [> `Post ])
             a_s ],
        'a, 'gn, 'pn, [< registrable > `Registrable ], 'return2)
       service
The function post_service ~fallback ~post_params () creates a service that takes post_params as POST parameters and share the same path and GET parameters than the service fallback.

POST parameters couldn't contain a suffix parameter.

The service fallback should be an (internal) attached service without POST parameters ; it couldn't be a preapplied service. This argument enforces the creation of an equivalent service ( i.e. a service with the same path and GET parameters ) to be served when POST parameters are missing. Thus, the user cannot put a bookmark on a page that does not exist.

See Eliom_service.service for a description of optional ~https, ~keep_nl_params and ~priority parameters .


Attached coservices


val coservice : ?name:string ->
       ?csrf_safe:bool ->
       ?csrf_scope:[< Eliom_common.user_scope ] ->
       ?csrf_secure:bool ->
       ?max_use:int ->
       ?timeout:float ->
       ?https:bool ->
       fallback:(unit, unit,
                 [ `Attached of
                     ([ `Internal of [ `Service ] ], [ `Get ]) a_s ],
                 [ `WithoutSuffix ], unit, unit, [< registrable ],
                 'return1)
                service ->
       ?keep_nl_params:[ `All | `None | `Persistent ] ->
       get_params:('get, [ `WithoutSuffix ], 'gn) Eliom_parameter.params_type ->
       unit ->
       ('get, unit,
        [> `Attached of
             ([> `Internal of [> `Coservice ] ], [> `Get ]) a_s ],
        [ `WithoutSuffix ], 'gn, unit,
        [< registrable > `Registrable ], 'return2)
       service
The function coservice ~fallback ~get_params creates an at the same path than the service fallback and taking get_params as GET parameters.

GET parameters of coservice couldn't contain a suffix parameter.

The service fallback should be an (internal) attached service without any GET or POST parameters ; it could be a preapplied service.

The optional ~name parameter Coservices can be named if the ?name optional parameter is present or anonymous (in that case, a coservice number will be generated).

The optional ~timeout parameter specifies a timeout (in seconds) after which the coservice will disappear. This amount of time is computed from the creation or from the last call to the service. The default is "no timeout". The optional ~max_use parameter specifies that the service can be used only a fixed number of times. The default is "no limitation".

If the optional ~csrf_safe parameter is true, it will create a . In that case the ~name parameter is ignored. The default is false.

The ~csrf_scope and ~csrf_secure, if present, should respectively correspond to the ~scope and ~secure parameters that will be given to the associated register function. Otherwise the registration will fail with . See Eliom_registration.Html5.register, Eliom_registration.App.register or any other Eliom_registration.*.register functions for a description of those parameters.

See Eliom_service.service for a description of the optional ~https and ~keep_nl_params parameters .

val post_coservice : ?name:string ->
       ?csrf_safe:bool ->
       ?csrf_scope:[< Eliom_common.user_scope ] ->
       ?csrf_secure:bool ->
       ?max_use:int ->
       ?timeout:float ->
       ?https:bool ->
       fallback:('get, unit,
                 [ `Attached of
                     ([ `Internal of [< `Coservice | `Service ] ], [ `Get ])
                     a_s ],
                 [< suff ] as 'a, 'gn, unit, [< `Registrable ],
                 'return1)
                service ->
       ?keep_nl_params:[ `All | `None | `Persistent ] ->
       post_params:('post, [ `WithoutSuffix ], 'pn) Eliom_parameter.params_type ->
       unit ->
       ('get, 'post,
        [> `Attached of
             ([> `Internal of [> `Coservice ] ], [> `Post ]) a_s ],
        'a, 'gn, 'pn, [< registrable > `Registrable ], 'return2)
       service
The function post_coservice ~fallback ~get_params creates an with the same path and GET parameters than the service fallback and taking post_params as POST parameters.

POST parameters couldn't contain a suffix parameter.

The service fallback should be an (internal) attached service or coservice without any POST parameters ; it could be a preapplied service.

See Eliom_service.coservice for a description of optional parameters.


Non attached coservices


val coservice' : ?name:string ->
       ?csrf_safe:bool ->
       ?csrf_scope:[< Eliom_common.user_scope ] ->
       ?csrf_secure:bool ->
       ?max_use:int ->
       ?timeout:float ->
       ?https:bool ->
       ?keep_nl_params:[ `All | `None | `Persistent ] ->
       get_params:('get, [ `WithoutSuffix ], 'gn) Eliom_parameter.params_type ->
       unit ->
       ('get, unit, [> `Nonattached of [> `Get ] na_s ],
        [ `WithoutSuffix ], 'gn, unit,
        [< registrable > `Registrable ], 'return)
       service
The function coservice' ~get_param creates a taking get_params as extra GET parameters.

GET parameters of coservice' couldn't contain a suffix parameter.

See Eliom_service.service for a description of the optional ~https and ~keep_nl_params parameters ; see Eliom_service.coservice for others optional parameters.

val post_coservice' : ?name:string ->
       ?csrf_safe:bool ->
       ?csrf_scope:[< Eliom_common.user_scope ] ->
       ?csrf_secure:bool ->
       ?max_use:int ->
       ?timeout:float ->
       ?https:bool ->
       ?keep_nl_params:[ `All | `None | `Persistent ] ->
       ?keep_get_na_params:bool ->
       post_params:('post, [ `WithoutSuffix ], 'pn) Eliom_parameter.params_type ->
       unit ->
       (unit, 'post, [> `Nonattached of [> `Post ] na_s ],
        [ `WithoutSuffix ], unit, 'pn,
        [< registrable > `Registrable ], 'return)
       service
The function post_coservice' ~get_param creates a taking post_params as POST parameters.

POST parameters couldn't contain a suffix parameter.

If the optional parameter ~keep_get_na_params is false, GET non-attached parameters of the current page won't be kept in the URL (if any) when you create a POST form to this coservice. The default is true.

See Eliom_service.service for a description of the optional ~https and ~keep_nl_params parameters ; see Eliom_service.coservice for others optional parameters.


Predefined services



Static files


val static_dir : unit ->
       (string list, unit,
        [> `Attached of
             ([> `Internal of [> `Service ] ], [> `Get ]) a_s ],
        [ `WithSuffix ], [ `One of string list ] Eliom_parameter.param_name, 
        unit, [< registrable > `Unregistrable ], 'return)
       service
The predefined service static_dir allows one to create links to static files. This service takes the name of a static file as a parameter (a string list, slash separated). The actual directory in filesystem where static pages will be found must be set up in the configuration file with the staticmod extension.
val https_static_dir : unit ->
       (string list, unit,
        [> `Attached of
             ([> `Internal of [> `Service ] ], [> `Get ]) a_s ],
        [ `WithSuffix ], [ `One of string list ] Eliom_parameter.param_name, 
        unit, [< registrable > `Unregistrable ], 'return)
       service
Same as Eliom_service.static_dir but forcing https link.
val static_dir_with_params : ?keep_nl_params:[ `All | `None | `Persistent ] ->
       get_params:('a, [ `WithoutSuffix ], 'an) Eliom_parameter.params_type ->
       unit ->
       (string list * 'a, unit,
        [> `Attached of
             ([> `Internal of [> `Service ] ], [> `Get ]) a_s ],
        [ `WithSuffix ], [ `One of string list ] Eliom_parameter.param_name * 'an,
        unit, [< registrable > `Unregistrable ], 'return)
       service
Like static_dir, but allows one to put GET parameters
val https_static_dir_with_params : ?keep_nl_params:[ `All | `None | `Persistent ] ->
       get_params:('a, [ `WithoutSuffix ], 'an) Eliom_parameter.params_type ->
       unit ->
       (string list * 'a, unit,
        [> `Attached of
             ([> `Internal of [> `Service ] ], [> `Get ]) a_s ],
        [ `WithSuffix ], [ `One of string list ] Eliom_parameter.param_name * 'an,
        unit, [< registrable > `Unregistrable ], 'return)
       service
Same as Eliom_service.static_dir_with_params but forcing https link.

Void non-attached coservices


val void_coservice' : (unit, unit, [> `Nonattached of 'a na_s ], [ `WithoutSuffix ],
        unit, unit, [< registrable > `Unregistrable ], 'return)
       service
The service void_coservice' is a predefined non-attached action with special behaviour: it has no parameter at all, even non-attached parameters. Use it if you want to make a link to the current page without non-attached parameters. It is almost equivalent to a POST non-attached service without POST parameters, on which you register an action that does nothing, but you can use it with <a> links, not only forms. It does not keep non attached GET parameters.
val https_void_coservice' : (unit, unit, [> `Nonattached of 'a na_s ], [ `WithoutSuffix ],
        unit, unit, [< registrable > `Unregistrable ], 'return)
       service
Same as Eliom_service.void_coservice' but forcing https.
val void_hidden_coservice' : (unit, unit, [> `Nonattached of 'a na_s ], [ `WithoutSuffix ],
        unit, unit, [< registrable > `Unregistrable ], 'return)
       service
Same as Eliom_service.void_coservice' but keeps non attached GET parameters.
val https_void_hidden_coservice' : (unit, unit, [> `Nonattached of 'a na_s ], [ `WithoutSuffix ],
        unit, unit, [< registrable > `Unregistrable ], 'return)
       service
Same as Eliom_service.void_hidden_coservice' but forcing https.

Miscellaneous


val preapply : service:('a, 'b, [> `Attached of ('d, 'dd) a_s ] as 'c,
                [< suff ], 'e, 'f, [< registrable ],
                'return)
               service ->
       'a ->
       (unit, 'b, 'c, [ `WithoutSuffix ], unit, 'f,
        [< registrable > `Unregistrable ], 'return)
       service
The function preapply ~service paramaters creates a new service by preapplying service to the GET parameters. It is not possible to register a handler on an preapplied service ; preapplied services may be used in links or as fallbacks for coservices
val add_non_localized_get_parameters : params:('p, [ `WithoutSuffix ], 'pn) Eliom_parameter.non_localized_params ->
       service:('a, 'b, 'c, [< suff ] as 'd, 'e, 'f,
                [< registrable ] as 'g, 'return)
               service ->
       ('a * 'p, 'b, 'c, 'd, 'e * 'pn, 'f, 'g, 'return) service
The function add_non_localized_get_parameters ~params ~service Adds non localized GET parameters params to service. See the Eliom manual for more information about .
val add_non_localized_post_parameters : params:('p, [ `WithoutSuffix ], 'pn) Eliom_parameter.non_localized_params ->
       service:('a, 'b, 'c, [< suff ] as 'd, 'e, 'f,
                [< registrable ] as 'g, 'return)
               service ->
       ('a, 'b * 'p, 'c, 'd, 'e, 'f * 'pn, 'g, 'return) service
Same as Eliom_service.add_non_localized_get_parameters but with POST parameters.
val unregister : ?scope:[< Eliom_common.scope ] ->
       ?secure:bool ->
       ('a, 'b,
        [< `Attached of ([> `Internal of 'c ], [< `Get | `Post ]) a_s
         | `Nonattached of 'd na_s ],
        [< suff ], 'f, 'g, [< registrable ], 'return)
       service -> unit
The function unregister service unregister the service handler previously associated to service with Eliom_registration.Html5.register, Eliom_registration.App.register or any other Eliom_registration.*.register functions. See the documentation of those functions for a description of the ~scope and ~secure optional parameters.