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 ], +'d, +'e , +[< registrable ], +'f) 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 . - 'd is a phantom type, subtype of Eliom_service.suff stating the kind of parameters it uses: suffix or not. - 'e is the type of GET parameters names. See Eliom_parameter.param_name and form generation functions (e. g. Eliom_registration.Html5.get_form ). - 'f is the type of POST parameters names. See Eliom_parameter.param_name and form generation functions (e. g. Eliom_registration.Html5.post_form ). - 'g is a phantom type, subtype of Eliom_service.registrable , telling if it is possible to register a handler on this service. - 'h 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:('a, [< suff ] as 'b, 'c) Eliom_parameter.params_type -> unit -> ('a, unit, [> `Attached of ([> `Internal of [> `Service ] ], [> `Get ]) a_s ], 'b, 'c, unit, [< registrable > `Registrable ], 'd) 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:('a, [< suff ] as 'b, 'c) Eliom_parameter.params_type -> unit -> ('a, unit, [> `Attached of ([> `External ], [> `Get ]) a_s ], 'b, 'c, unit, [< registrable > `Unregistrable ], 'd) 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:('a, [< suff ] as 'b, 'c) Eliom_parameter.params_type -> post_params:('d, [ `WithoutSuffix ], 'e) Eliom_parameter.params_type -> unit -> ('a, 'd, [> `Attached of ([> `External ], [> `Post ]) a_s ], 'b, 'c, 'e, [< registrable > `Unregistrable ], 'f) service Same as Eliom_service.external_service but with POST method. val post_service : ?https:bool -> fallback:('a, unit, [ `Attached of ([ `Internal of [ `Coservice | `Service ] ], [ `Get ]) a_s ], [< suff ] as 'b, 'c, unit, [< `Registrable ], 'd) service -> ?keep_nl_params:[ `All | `None | `Persistent ] -> ?priority:int -> post_params:('e, [ `WithoutSuffix ], 'f) Eliom_parameter.params_type -> unit -> ('a, 'e, [> `Attached of ([> `Internal of [ `Coservice | `Service ] ], [> `Post ]) a_s ], 'b, 'c, 'f, [< registrable > `Registrable ], 'g) 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 ], 'a) service -> ?keep_nl_params:[ `All | `None | `Persistent ] -> get_params:('b, [ `WithoutSuffix ], 'c) Eliom_parameter.params_type -> unit -> ('b, unit, [> `Attached of ([> `Internal of [> `Coservice ] ], [> `Get ]) a_s ], [ `WithoutSuffix ], 'c, unit, [< registrable > `Registrable ], 'd) 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:('a, unit, [ `Attached of ([ `Internal of [< `Coservice | `Service ] ], [ `Get ]) a_s ], [< suff ] as 'b, 'c, unit, [< `Registrable ], 'd) service -> ?keep_nl_params:[ `All | `None | `Persistent ] -> post_params:('e, [ `WithoutSuffix ], 'f) Eliom_parameter.params_type -> unit -> ('a, 'e, [> `Attached of ([> `Internal of [> `Coservice ] ], [> `Post ]) a_s ], 'b, 'c, 'f, [< registrable > `Registrable ], 'g) 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:('a, [ `WithoutSuffix ], 'b) Eliom_parameter.params_type -> unit -> ('a, unit, [> `Nonattached of [> `Get ] na_s ], [ `WithoutSuffix ], 'b, unit, [< registrable > `Registrable ], 'c) 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:('a, [ `WithoutSuffix ], 'b) Eliom_parameter.params_type -> unit -> (unit, 'a, [> `Nonattached of [> `Post ] na_s ], [ `WithoutSuffix ], unit, 'b, [< registrable > `Registrable ], 'c) 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 ], 'a) 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 ], 'a) 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 ], 'b) 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 * 'b, unit, [< registrable > `Unregistrable ], 'c) 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 ], 'b) 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 * 'b, unit, [< registrable > `Unregistrable ], 'c) 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 ], 'b) 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 ], 'b) 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 ], 'b) 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 ], 'b) service Same as Eliom_service.void_hidden_coservice' but forcing https. === Miscellaneous === val preapply : service:('a, 'b, [> `Attached of ('d, 'e) a_s ] as 'c, [< suff ], 'f, 'g, [< registrable ], 'h) service -> 'a -> (unit, 'b, 'c, [ `WithoutSuffix ], unit, 'g, [< registrable > `Unregistrable ], 'h) 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:('a, [ `WithoutSuffix ], 'b) Eliom_parameter.non_localized_params -> service:('c, 'd, 'e, [< suff ] as 'f, 'g, 'h, [< registrable ] as 'i, 'j) service -> ('c * 'a, 'd, 'e, 'f, 'g * 'b, 'h, 'i, 'j) 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:('a, [ `WithoutSuffix ], 'b) Eliom_parameter.non_localized_params -> service:('c, 'd, 'e, [< suff ] as 'f, 'g, 'h, [< registrable ] as 'i, 'j) service -> ('c, 'd * 'a, 'e, 'f, 'g, 'h * 'b, 'i, 'j) 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 ], 'e, 'f, [< registrable ], 'g) 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. === Eliom application services === val onload : Dom_html.event Eliom_content_core.Xml.caml_event_handler -> unit The function onload evt will register the function evt to be executed on client side once the App page generated by the current service handler is loaded. This function should not be called outside of a service handler. Use it with Eliom's syntax extension for client side code, for example: onload {{ Firebug.console.debug(Js.string Hello world! ) }} . val onunload : Dom_html.event Eliom_content_core.Xml.caml_event_handler -> unit The function onunload evt will register the function evt to be executed on client side when leaving the App page generated by the current service handler. This function should not be called outside of a service handler. Use it with Eliom's syntax extension for client side code, for example: onunload {{ Firebug.console.debug(Js.string Goodbye! ) }} .