.TH "Eliom_service" 3o 2014-07-10 OCamldoc "" .SH NAME Eliom_service \- Creation and manipulation of Eliom services. .SH Module Module Eliom_service .SH Documentation .sp Module .BI "Eliom_service" : .B sig end .sp Creation and manipulation of Eliom services\&. .sp .sp .sp .sp .PP .B === See the Eliom manual for a detailed introduction to the concept of .B {% <> %}\&. .B .B .B {% <> >> %} === .PP .PP .B === The main functions to create services are in modules .B {% <> %} (default), .B {% <> %} .B (for services returning OCaml values) and .B {% <> %} .B (for services belonging to an Eliom client\-server app)\&. === .PP .PP .B === .B Type definitions for services .B === .PP .PP .B === .B Services kind .B === .PP .PP .B === .B Internal or external .B === .PP .I type servcoserv = .B [ `Coservice | `Service ] .sp An internal attached service could either be a .B `Service or a .B `Coservice \&. .sp .sp .I type attached_service_kind = .B [ `External | `Internal of servcoserv ] .sp An attached service could either be an .B `Internal Eliom service or an abstraction for an .B `External service\&. .sp .sp .PP .B === .B POST or GET parameters .B === .PP .I type getpost = .B [ `Delete | `Get | `Post | `Put ] .sp The kind of a service is .B `Post when there is at least one POST parameters\&. It is .B `Get otherwise\&. .sp .sp .PP .B === .B Attached or Non\-attached .B === .PP .I type .B (+'a, +'b) .I a_s .sp The abstract type for attached service representation\&. .sp \- .B \&'a is a subtype of .B Eliom_service\&.attached_service_kind .sp \- .B \&'b is a subtype of .B Eliom_service\&.getpost .sp .sp .I type .B +'a .I na_s .sp The abstract type for non\-attached service representation\&. .sp \- .B \&'a is a subtype of .B Eliom_service\&.getpost .sp .sp .I type service_kind = .B [ `Attached of .B (attached_service_kind, getpost) .B a_s .B | `Nonattached of getpost na_s ] .sp The type .B service_kind describe all four kind of services: .sp \-external (attached) services .sp \-(internal) attached services .sp \-(internal) attached coservices .sp \-(internal) non\-attached coservices .sp .sp .PP .B === .B Common subtypes of service_kind .B === .PP .I type get_service_kind = .B [ `Attached of .B (attached_service_kind, [ `Get ]) a_s .B | `Nonattached of [ `Get ] na_s ] .sp Restriction of .B service_kind to GET services\&. .sp .sp .I type post_service_kind = .B [ `Attached of .B (attached_service_kind, [ `Post ]) a_s .B | `Nonattached of [ `Post ] na_s ] .sp Restriction of .B service_kind to POST services\&. .sp .sp .I type put_service_kind = .B [ `Attached of .B (attached_service_kind, [ `Put ]) a_s .B | `Nonattached of [ `Put ] na_s ] .sp Restriction of .B service_kind to PUT services\&. .sp .sp .I type delete_service_kind = .B [ `Attached of .B (attached_service_kind, [ `Delete ]) a_s .B | `Nonattached of [ `Delete ] na_s ] .sp Restriction of .B service_kind to DELETE services\&. .sp .sp .I type attached = .B [ `Attached of .B (attached_service_kind, getpost) .B a_s ] .sp Restriction of .B service_kind to attached services\&. .sp .sp .I type nonattached = .B [ `Nonattached of getpost na_s ] .sp Restriction of .B service_kind to non\-attached services\&. .sp .sp .I type internal_service_kind = .B [ `Attached of .B ([ `Internal of servcoserv ], getpost) .B a_s .B | `Nonattached of getpost na_s ] .sp Restriction of .B service_kind to internal services\&. .sp .sp .PP .B === .B Kind of parameters .B === .PP .I type suff = .B [ `WithSuffix | `WithoutSuffix ] .sp The kind of parameters for a service is .B `WithSuffix when it have a suffix parameter, for examples .B Eliom_parameter\&.suffix or .B Eliom_parameter\&.suffix_prod \&. Otherwise it is .B `WithoutSuffix \&. .sp .sp .PP .B === .B Registrable service .B === .PP .I type registrable = .B [ `Registrable | `Unregistrable ] .sp A service is .B `Registrable only if it isn\&'t a pre\-applied service, see .B Eliom_service\&.preapply \&. .sp .sp .PP .B === .B Abstract type of services .B === .PP .I type .B ('a, 'b, +'c, +[< suff ], +'e, +'f .B , +[< registrable ], +'h) .I service .sp Type of services\&. .sp \- .B \&'a is the type of GET parameters expected by the service\&. .sp \- .B \&'b is the type of POST parameters expected by the service\&. .sp \- .B \&'c describes the services\&'s kind: attached or non\-attached, internal or external, GET only or with POST parameters\&. It is a subtype of .B Eliom_service\&.service_kind \&. .sp \-the type paremeter of subtype .B Eliom_service\&.suff states the kind of parameters it uses: suffix or not\&. .sp \- .B \&'d is the type of GET parameters names\&. See .B Eliom_parameter\&.param_name and form generation functions (e\&. g\&. .B Eliom_content\&.Html5\&.D\&.get_form )\&. .sp \- .B \&'e is the type of POST parameters names\&. See .B Eliom_parameter\&.param_name and form generation functions (e\&. g\&. .B Eliom_content\&.Html5\&.D\&.post_form )\&. .sp \-the type parameter of subtype .B Eliom_service\&.registrable tells if it is possible to register a handler on this service\&. .sp \- .B \&'f is an information on what the service returns\&. See .B Eliom_registration\&.kind \&. .sp .sp .I type http_service = .B [ `Http ] .sp Types of groups of services\&. .sp .sp .I type appl_service = .B [ `Appl ] .sp .sp .I type .B 'a .I ocaml_service .sp .sp .I type non_ocaml_service = .B [ `Appl | `Http ] .sp The type .B non_ocaml_service is used as phantom type parameters for the .B Eliom_registration\&.kind \&. It used to type functions that operates over service that do not returns OCaml values, like .B appl_self_redirect \&. .sp .sp .I type .B 'rt .I rt .sp 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 .B ?rt of service creation functions (like <>), using the following value\&. .sp .sp .I val rt : .B 'rt rt .sp .sp .PP .B === .B Registration of services .B === .PP .I module Http : .B sig end .sp Default module for creating services .sp .sp .I module App : .B sig end .sp Module for creating services returning applications .sp .sp .I module Ocaml : .B sig end .sp Module for creating services that return OCaml values .sp .sp .I module Unsafe : .B sig end .sp Module for creating services without specifying the return type .sp .sp .PP .B === .B Static loading of Eliom modules .B === .PP .PP .B === This functionality allows one to register initialization functions for .B Eliom modules which will be executed when the corresponding module .B is loaded in ocsigenserver\&.conf\&. .B If the module is loaded dynamically, you probably don\&'t need this\&. .B But if the module is linked statically, some computations, .B like service registrations must be delayed\&. === .PP .I val register_eliom_module : .B string -> (unit -> unit) -> unit .sp The function .B register_eliom_module mod f is used to register the initialization function .B f to be executed when then module .B mod is loaded by Ocsigen server\&. The module .B mod could either be a dynamically loaded module or linked statically into the server: in each case, the .B f function will be invoked when the module is initialized in the configuration file using .B .B \&.\&.\&. \&. If .B register_eliom_module is called twice with the same module name, the second initialization function will replace the previous one\&. .sp .sp .PP .B === .B Predefined services .B === .PP .PP .B === .B Static files .B === .PP .I val static_dir : .B unit -> .B (string list, unit, .B [> `Attached of .B ([> `Internal of [> `Service ] ], [> `Get ]) a_s ], .B [ `WithSuffix ], [ `One of string list ] Eliom_parameter.param_name, .B unit, [< registrable > `Unregistrable ], .B [> http_service ]) .B service .sp The predefined service .B 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\&. .sp .sp .I val https_static_dir : .B unit -> .B (string list, unit, .B [> `Attached of .B ([> `Internal of [> `Service ] ], [> `Get ]) a_s ], .B [ `WithSuffix ], [ `One of string list ] Eliom_parameter.param_name, .B unit, [< registrable > `Unregistrable ], .B [> http_service ]) .B service .sp Same as .B Eliom_service\&.static_dir but forcing https link\&. .sp .sp .I val static_dir_with_params : .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B get_params:('a, [ `WithoutSuffix ], 'an) Eliom_parameter.params_type -> .B unit -> .B (string list * 'a, unit, .B [> `Attached of .B ([> `Internal of [> `Service ] ], [> `Get ]) a_s ], .B [ `WithSuffix ], [ `One of string list ] Eliom_parameter.param_name * 'an, .B unit, [< registrable > `Unregistrable ], .B [> http_service ]) .B service .sp Like .B static_dir , but allows one to put GET parameters .sp .sp .I val https_static_dir_with_params : .B ?keep_nl_params:[ `All | `None | `Persistent ] -> .B get_params:('a, [ `WithoutSuffix ], 'an) Eliom_parameter.params_type -> .B unit -> .B (string list * 'a, unit, .B [> `Attached of .B ([> `Internal of [> `Service ] ], [> `Get ]) a_s ], .B [ `WithSuffix ], [ `One of string list ] Eliom_parameter.param_name * 'an, .B unit, [< registrable > `Unregistrable ], .B [> http_service ]) .B service .sp Same as .B Eliom_service\&.static_dir_with_params but forcing https link\&. .sp .sp .PP .B === .B Void non\-attached coservices .B === .PP .I val void_coservice' : .B (unit, unit, [> `Nonattached of [> `Get ] na_s ], .B [ `WithoutSuffix ], unit, unit, .B [< registrable > `Unregistrable ], .B [> non_ocaml_service ]) .B service .sp The service .B 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 links, not only forms\&. It does not keep non attached GET parameters\&. .sp .sp .I val https_void_coservice' : .B (unit, unit, [> `Nonattached of [> `Get ] na_s ], .B [ `WithoutSuffix ], unit, unit, .B [< registrable > `Unregistrable ], .B [> non_ocaml_service ]) .B service .sp Same as .B Eliom_service\&.void_coservice\&' but forcing https\&. .sp .sp .I val void_hidden_coservice' : .B (unit, unit, [> `Nonattached of [> `Get ] na_s ], .B [ `WithoutSuffix ], unit, unit, .B [< registrable > `Unregistrable ], .B [> non_ocaml_service ]) .B service .sp Same as .B Eliom_service\&.void_coservice\&' but keeps non attached GET parameters\&. .sp .sp .I val https_void_hidden_coservice' : .B (unit, unit, [> `Nonattached of [> `Get ] na_s ], .B [ `WithoutSuffix ], unit, unit, .B [< registrable > `Unregistrable ], .B [> non_ocaml_service ]) .B service .sp Same as .B Eliom_service\&.void_hidden_coservice\&' but forcing https\&. .sp .sp .PP .B === .B Miscellaneous .B === .PP .I val preapply : .B service:('a, 'b, [> `Attached of ('d, 'dd) a_s ] as 'c, .B [< suff ], 'e, 'f, [< registrable ], .B 'return) .B service -> .B 'a -> .B (unit, 'b, 'c, [ `WithoutSuffix ], unit, 'f, .B [< registrable > `Unregistrable ], 'return) .B service .sp The function .B preapply ~service paramaters creates a new service by preapplying .B service to the GET .B 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 .sp .sp .I val attach_coservice' : .B fallback:(unit, unit, .B [< `Attached of .B ([< `Internal of 'sc1 ], [< `Get ]) a_s ], .B [< suff ], unit, unit, .B [< registrable ], 'return1) .B service -> .B service:('get, 'post, [< `Nonattached of 'gp na_s ], .B [< `WithoutSuffix ] as 'a, 'gn, 'pn, [< registrable ], .B 'return) .B service -> .B ('get, 'post, .B [> `Attached of ([> `Internal of [> `Coservice ] ], 'gp) a_s ], .B 'a, 'gn, 'pn, [< registrable > `Unregistrable ], 'return) .B service .sp .B attach_coservice\&' ~fallback ~service attaches the non\-attached coservice .B service on the URL of .B 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\&. .sp .sp .I val add_non_localized_get_parameters : .B params:('p, [ `WithoutSuffix ], 'pn) Eliom_parameter.non_localized_params -> .B service:('a, 'b, 'c, [< suff ] as 'd, 'e, 'f, .B [< registrable ] as 'g, 'return) .B service -> .B ('a * 'p, 'b, 'c, 'd, 'e * 'pn, 'f, 'g, 'return) service .sp The function .B add_non_localized_get_parameters ~params ~service Adds non localized GET parameters .B params to .B service \&. See the Eliom manual for more information about \&. .sp .sp .I val add_non_localized_post_parameters : .B params:('p, [ `WithoutSuffix ], 'pn) Eliom_parameter.non_localized_params -> .B service:('a, 'b, 'c, [< suff ] as 'd, 'e, 'f, .B [< registrable ] as 'g, 'return) .B service -> .B ('a, 'b * 'p, 'c, 'd, 'e, 'f * 'pn, 'g, 'return) service .sp Same as .B Eliom_service\&.add_non_localized_get_parameters but with POST parameters\&. .sp .sp .I val unregister : .B ?scope:[< Eliom_common.scope ] -> .B ?secure:bool -> .B ('a, 'b, .B [< `Attached of .B ([> `Internal of 'c ], [< `Delete | `Get | `Post | `Put ]) .B a_s .B | `Nonattached of 'd na_s ], .B [< suff ], 'f, 'g, [< registrable ], 'return) .B service -> unit .sp The function .B unregister service unregister the service handler previously associated to .B service with .B Eliom_registration\&.Html5\&.register , .B Eliom_registration\&.App\&.register or any other .B Eliom_registration .B \&.*\&.register functions\&. See the documentation of those functions for a description of the .B ~scope and .B ~secure optional parameters\&. .sp .sp