Creation and manipulation of eliom services.
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 {% <<a_manual chapter="server-services"|Eliom services>> %}. {% <<outline| <<header| **Table of contents** >> >> %} ===
=== The main functions to create services are in modules {% <<a_api subproject="server"|module Eliom_service.Http>> %} (default), {% <<a_api subproject="server"|module Eliom_service.Ocaml>> %} (for services returning OCaml values) and {% <<a_api subproject="server"|module Eliom_service.App>> %} (for services belonging to an Eliom client-server app). ===
=== 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 = [ `Delete | `Get | `Post | `Put ]
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 GET services.
type post_service_kind = [ `Attached of (attached_service_kind, [ `Post ]) a_s | `Nonattached of [ `Post ] na_s ]
Restriction of service_kind to POST services.
type put_service_kind = [ `Attached of (attached_service_kind, [ `Put ]) a_s | `Nonattached of [ `Put ] na_s ]
Restriction of service_kind to PUT services.
type delete_service_kind = [ `Attached of (attached_service_kind, [ `Delete ]) a_s | `Nonattached of [ `Delete ] na_s ]
Restriction of service_kind to DELETE services.
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_content.Html5.D.get_form ).
- 'e is the type of POST parameters names. See Eliom_parameter.param_name and form generation functions (e. g. Eliom_content.Html5.D.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 .
type http_service = [ `Http ]
Types of groups of services.
type appl_service = [ `Appl ]
type 'a ocaml_service
type non_ocaml_service = [ `Appl | `Http ]
The type non_ocaml_service is used as phantom type parameters for the Eliom_registration.kind . It used to type functions that operates over service that do not returns OCaml values, like appl_self_redirect .
type 'rt rt
Helper for typing OCaml services. In some cases, you may need to write the return type of the service manually. Instead of writing the full type of the service, (which may be huge), add a type constraint for parameter ?rt of service creation functions (like <<a_api subproject="server"|fun Eliom_service.Http.service>>), using the following value.
val rt : 'rt rt
=== Registration of services ===
module Http : sig end
Default module for creating services
module App : sig end
Module for creating services returning applications
module Ocaml : sig end
Module for creating services that return OCaml values
module Unsafe : sig end
Module for creating services without specifying the return type
=== Static loading of Eliom 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. If the module is loaded dynamically, you probably don't need this. But if the module is linked statically, some computations, like service registrations must be delayed. ===
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 <eliommodule ...> ... </eliommodule> . If register_eliom_module is called twice with the same module name, the second initialization function will replace the previous one.
=== 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 ], [> http_service ]) 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 ], [> http_service ]) 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 ], [> http_service ]) 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 ], [> http_service ]) service
Same as Eliom_service.static_dir_with_params but forcing https link.
=== Void non-attached coservices ===
val void_coservice' : (unit, unit, [> `Nonattached of [> `Get ] na_s ], [ `WithoutSuffix ], unit, unit, [< registrable > `Unregistrable ], [> non_ocaml_service ]) 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 [> `Get ] na_s ], [ `WithoutSuffix ], unit, unit, [< registrable > `Unregistrable ], [> non_ocaml_service ]) service
Same as Eliom_service.void_coservice' but forcing https.
val void_hidden_coservice' : (unit, unit, [> `Nonattached of [> `Get ] na_s ], [ `WithoutSuffix ], unit, unit, [< registrable > `Unregistrable ], [> non_ocaml_service ]) service
Same as Eliom_service.void_coservice' but keeps non attached GET parameters.
val https_void_hidden_coservice' : (unit, unit, [> `Nonattached of [> `Get ] na_s ], [ `WithoutSuffix ], unit, unit, [< registrable > `Unregistrable ], [> non_ocaml_service ]) 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 attach_coservice' : fallback:(unit, unit, [< `Attached of ([< `Internal of 'sc1 ], [< `Get ]) a_s ], [< suff ], unit, unit, [< registrable ], 'return1) service -> service:('get, 'post, [< `Nonattached of 'gp na_s ], [< `WithoutSuffix ] as 'a, 'gn, 'pn, [< registrable ], 'return) service -> ('get, 'post, [> `Attached of ([> `Internal of [> `Coservice ] ], 'gp) a_s ], 'a, 'gn, 'pn, [< registrable > `Unregistrable ], 'return) service
attach_coservice' ~fallback ~service attaches the non-attached coservice service on the URL of fallback . This allows to create a link to a non-attached coservice but with another URL than the current one. It is not possible to register something on the service returned by this function.
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 ], [< `Delete | `Get | `Post | `Put ]) 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.