Provided by: libeliom-ocaml-doc_3.0.3-4build2_all 
NAME
Eliom_service - Creation and manipulation of Eliom services.
Module
Module Eliom_service
Documentation
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.
- 'a is a subtype of Eliom_service.attached_service_kind
- 'b is a subtype of Eliom_service.getpost
type +'a na_s
The abstract type for non-attached service representation.
- 'a is a subtype of Eliom_service.getpost
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:
-external (attached) services
-(internal) attached services
-(internal) attached coservices
-(internal) non-attached coservices
=== 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.
- 'a is the type of GET parameters expected by the service.
- 'b is the type of POST parameters expected by the service.
- 'c describes the services's kind: attached or non-attached, internal or external, GET
only or with POST parameters. It is a subtype of Eliom_service.service_kind .
-the type paremeter of subtype Eliom_service.suff states the kind of parameters it uses:
suffix or not.
- 'd is the type of GET parameters names. See Eliom_parameter.param_name and form
generation functions (e. g. Eliom_registration.Html5.get_form ).
- 'e is the type of POST parameters names. See Eliom_parameter.param_name and form
generation functions (e. g. Eliom_registration.Html5.post_form ).
-the type parameter of subtype Eliom_service.registrable tells if it is possible to
register a handler on this service.
- 'f is an information on what the service returns. See Eliom_registration.kind .
=== 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.