Example

Write a string: "[Form.input ~input_type:`Text ~name:chaine Form.string)"

"]) 222) in Lwt.return [%html " Example "[f]""]) let form4 = Eliom_registration.Html.create ~path:(Eliom_service.Path ["form4"]) ~meth:(Eliom_service.Get Eliom_parameter.unit) (fun () () -> let module Html = Eliom_content.Html.D in let f = (Eliom_content.Html.D.Form.post_form ~service:(Eliom_service.extern ~prefix:"http://www.petizomverts.com" ~path:["zebulon"] ~meth:(Eliom_service.Post (int "i", string "chaine")) ()) (fun chaine -> [ [%html "

Write a string: "[Form.input ~input_type:`Text ~name:chaine Form.string]"

"]) 222) in Lwt.return (html (head (title (txt "form")) []) (body [f]))) ``` ## Advanced forms and parameters This section shows more advanced use of page parameters and corresponding forms. ### Parsing parameters using regular expressions Eliom\_parameter.regexp allows parsing page parameters using (Perl-compatible) regular expressions. We use the module Netstring\_pcre, from *OCamlnet*. See the documentation about OCamlnet for more information. The following example shows a service that accepts only parameters values enclosed between `{%html:%} and {%html:%}`: ```ocaml let r = Netstring_pcre.regexp "\\\\[(.*)\\\\]" let regexp = Eliom_registration.Html.create ~path:(Eliom_service.Path ["regexp"]) ~meth: (Eliom_service.Get Eliom_parameter.(regexp r "$1" (fun s -> s) "myparam")) (fun g () -> Lwt.return Html.D.(html (head (title (txt "")) []) (body [p [txt g]]))) ``` ```ocaml let myregexp = Netstring_pcre.regexp "\\[(.*)\\]" let regexpserv = Eliom_registration.Html.create ~path:(Eliom_service.Path ["regexp"]) ~meth:(Eliom_service.Get Eliom_parameter.(regexp myregexp "$1" (fun s -> s) "myparam")) (fun g () -> Lwt.return Html.D.(html (head (title (txt "")) []) (body [p [txt g]]))) ``` ### Boolean checkboxes Page may take parameter of type bool. A possible use of this type is in a form with *boolean checkboxes*, as in the example below: ```ocaml (* Form with bool checkbox: *) let bool_params = Eliom_registration.Html.create ~path:(Eliom_service.Path ["bool"]) ~meth:(Eliom_service.Get Eliom_parameter.(bool "case")) (fun case () -> let module Html = Html.D in Lwt.return [%html " Example

"[txt (if case then "checked" else "not checked")]"

"]) let create_form_bool casename = let module Html = Html.D in [ [%html "

check? "[Form.bool_checkbox_one ~name:casename ()]"
"[Form.input ~input_type:`Submit ~value:"Click" Form.string]"

"] ] let form_bool = Eliom_registration.Html.create ~path:(Eliom_service.Path ["formbool"]) ~meth:(Eliom_service.Get Eliom_parameter.unit) (fun () () -> let module Html = Html.D in let f = Form.get_form ~service:bool_params create_form_bool in Lwt.return [%html " Example "[f]" "]) ``` *Important warning:* As you can see, browsers do not send any value for unchecked boxes\! An unchecked box is equivalent to no parameter at all\! Thus it is not possible to distinguish between a service taking a boolean and a service taking no parameter at all (if they share the same URL). In Eliom services with higher priority are tried first, and then they are tried in order of registration. The first matching service will answer.
Other types similar to bool: - `Eliom_parameter.opt` (page taking an optional parameter), - `Eliom_parameter.sum` (either a parameter or another). See [`Eliom_parameter_sigs.S`](./eliom.server/Eliom_parameter_sigs-module-type-S.md). ### Type set Page may take several parameters of the same name. It is useful when you want to create a form with a variable number of fields. To do that with Eliom, use the type `Eliom_parameter.set`. For example, set int "val" means that the page will take zero, one, or several parameters of name "val", all of type int. The function you register will receive the parameters in a list. Example: ```ocaml let set = Eliom_registration.Html.create ~path:(Eliom_service.Path ["set"]) ~meth:(Eliom_service.Get Eliom_parameter.(set string "s")) (fun l () -> let module Html = Html.D in let ll = List.map (fun s -> [%html ""[txt s]""]) l in Lwt.return [%html " Example

You sent: "ll"

"]) ``` These parameters may come from several kinds of widgets in forms. Here is an example of a form with several checkboxes, all sharing the same name, but with different values: ```ocaml (* form to set *) let setform = Eliom_registration.Html.create ~path:(Eliom_service.Path ["setform"]) ~meth:(Eliom_service.Get Eliom_parameter.unit) (fun () () -> Lwt.return (html (head (title (txt "")) []) (body [h1 [txt "Set Form"]; Form.get_form ~service:set (fun n -> [p [txt "Form to set: "; Form.checkbox ~name:n ~value:"box1" Form.string; Form.checkbox ~name:n ~value:"box2" ~checked:true Form.string; Form.checkbox ~name:n ~value:"box3" Form.string; Form.checkbox ~name:n ~value:"box4" Form.string; Form.input ~input_type:`Submit ~value:"Click" Form.string]]) ]))) ``` Once again, note that there is no difference between an empty set or no parameter at all. If you register a service without parameters and a service with a set of parameters on the same URL, the service with higher priority, or the firstly registered service that matches, will answer. ### Select Here is an example of a select box. ```ocaml let select_example_result = Eliom_registration.Html.create ~path:(Eliom_service.Path ["select"]) ~meth:(Eliom_service.Get Eliom_parameter.(string "s")) (fun g () -> Lwt.return (html (head (title (txt "")) []) (body [p [txt "You selected: "; strong [txt g]]]))) let create_select_form = (fun select_name -> Html.D.( [p [txt "Select something: "; Form.select Form.string ~name:select_name (Form.Option ([] (* attributes *), "Bob" (* value *), None (* Content, if different from value *), false (* not selected *))) (* first line *) [Form.Option ([], "Marc", None, false); (Form.Optgroup ([], "Girls", ([], "Karin", None, false), [([a_disabled ()], "Juliette", None, false); ([], "Alice", None, true); ([], "Germaine", Some (txt "Bob's mother"), false)]))] ; Form.input ~input_type:`Submit ~value:"Send" Form.string]] )) let select_example = Eliom_registration.Html.create ~path:(Eliom_service.Path ["select"]) ~meth:(Eliom_service.Get Eliom_parameter.unit) (fun () () -> let open Html.D in let f = Form.get_form ~service:select_example_result create_select_form in Lwt.return (html (head (title (txt "")) []) (body [f]))) ``` To do "multiple" select boxes, use functions like `Eliom_content.Html.D.Form.multiple_select`. As you can see in the type, the service must be declared with parameters of type `Eliom_parameter.set`. ### Clickable images Here is an example of clickable image. You receive the coordinates the user clicked on. ```ocaml let coord = Eliom_registration.Html.create ~path:(Eliom_service.Path ["coord"]) ~meth:(Eliom_service.Get Eliom_parameter.(coordinates "coord")) (fun c () -> let module Html = Html.D in Lwt.return [%html" Example

You clicked on coordinates: ("[txt (string_of_int c.abscissa)]", "[txt (string_of_int c.ordinate)]")

"]) (* form to image *) let imageform = Eliom_registration.Html.create ~path:(Eliom_service.Path ["imageform"]) ~meth:(Eliom_service.Get Eliom_parameter.unit) (fun () () -> Lwt.return (html (head (title (txt "")) []) (body [h1 [txt "Image Form"]; Form.get_form ~service:coord (fun n -> [p [Form.image_input ~src:(make_uri ~service:(Eliom_service.static_dir ()) ["ocsigen5.png"]) ~name:n ()]]) ]))) ``` ### Type list Another way (than `Eliom_parameter.set`) to do variable length forms is to use indexed lists (using `Eliom_parameter.list`). The use of that feature is a bit more complex than set. Here is an example of service taking an indexed list as parameter: ```ocaml (* lists *) let service_list = Eliom_registration.Html.create ~path:(Eliom_service.Path ["thepath"]) ~meth:(Eliom_service.Get Eliom_parameter.(list "a" (string "str"))) (fun l () -> let open Eliom_content.Html.D in let ll = List.map (fun s -> strong [txt s]) l in Lwt.return (html (head (title (txt "Example")) []) (body [p ll]))) ``` *Warning:* As for sets or bools, if a request has no parameter, it will be considered as the empty list. Services with higher priority are tried first, otherwise they are tried in order of registration. As you see, the names of each list element is built from the name of the list, the name of the list element, and an index. To spare you creating yourself these names, Eliom provides you an iterator to create them. ```ocaml (* Form with list: *) let create_listform f = (* Here, f.it is an iterator like List.map, but it must be applied to a function taking 3 arguments (unlike 1 in map), the first one being the name of the parameter, and the second one the element of list. The last parameter of f.it is the code that must be appended at the end of the list created *) let open Eliom_content.Html.D in f.Eliom_parameter.it (fun stringname v init -> p [ txt "Write the value for " ; txt v ; txt " :" ; Form.input ~input_type:`Text ~name:stringname Form.string ] :: init) ["one"; "two"; "three"; "four"] [p [Form.input ~input_type:`Submit ~value:"Click" Form.string]] let _ = Eliom_registration.Html.create ~path:(Eliom_service.Path ["listform"]) ~meth:(Eliom_service.Get Eliom_parameter.unit) (fun () () -> let open Eliom_content.Html.D in let f = Form.get_form ~service:service_list create_listform in Lwt.return (html (head (title (txt "Example")) []) (body [f]))) ``` *Important warning:* As we have seen in the section about boolean (or optional) parameters, it is not possible to distinguish between a boolean with value "false", and no parameter at all. This causes problems if you create a list of boolean or optional values, as it is not possible to know the length of the list. In that case, Eliom always takes the shortest possible list. ### Forms and suffixes Service with "suffix" URLs have an equivalent version with usual parameters, allowing creation of forms towards such services. Example: ```ocaml (* Form for service with suffix: *) let create_suffixform ((suff, endsuff),i) = let module Html = Eliom_content.Html.D in [%html "

Write the suffix: "[Form.input ~input_type:`Text ~name:suff Form.int]"
Write a string: "[Form.input ~input_type:`Text ~name:endsuff Form.string] "
Write an int: "[Form.input ~input_type:`Text ~name:i Form.int]"
"[Form.input ~input_type:`Submit ~value:"Click" Form.string]"

"] let suffixform = Eliom_registration.Html.create ~path:(Eliom_service.Path ["suffixform"]) ~meth:(Eliom_service.Get Eliom_parameter.unit) (fun () () -> let f = Form.get_form ~service:isuffix create_suffixform in let module Html = Eliom_content.Html.D in Lwt.return [%html " Example "[f]" "]) ``` Decode the URL encoded string using `Ocsigen_lib.Url.string_of_url_path ~encode:false` ### Uploading files The `Eliom_parameter.file` parameter type allows files to be sent in your request. The service gets something of type `Ocsigen_extensions.file_info`. You can extract information using this using these functions (from [`Eliom_request_info`](./eliom.server/Eliom_request_info.md)): ```ocaml val get_tmp_filename : Ocsigen_extensions.file_info -> string val get_filesize : Ocsigen_extensions.file_info -> int64 val get_original_filename : Ocsigen_extensions.file_info -> string ``` [`Eliom_request_info.get_tmp_filename`](./eliom.server/Eliom_request_info.md#val-get_tmp_filename) returns the actual name of the uploaded file on the hard drive. [`Eliom_request_info.get_original_filename`](./eliom.server/Eliom_request_info.md#val-get_original_filename) gives the original filename. To enable file upload, you must configure a directory for uploaded files in Ocsigen's configuration file. For example: \/tmp\ Files are kept in this directory only while processing the request. They are automatically removed afterwards. Therefore, your services must copy the files somewhere else, if the files are to be kept. In the following example, we create a new hard link to the file to keep it. (The destination must be on the same partition of the disk.) ```ocaml let upload = Eliom_service.create ~path:(Eliom_service.Path ["upload"]) ~meth:(Eliom_service.Get unit) () let upload2 = Eliom_registration.Html.create ~path:(Eliom_service.Path ["upload"]) ~meth:(Eliom_service.Post (Eliom_parameter.unit, Eliom_parameter.file "file")) (fun () file -> let to_display = let newname = "/tmp/thefile" in (try Unix.unlink newname; with _ -> ()); Lwt_log.ign_debug (Eliom_request_info.get_tmp_filename file); Unix.link (Eliom_request_info.get_tmp_filename file) newname; let fd_in = open_in newname in try let line = input_line fd_in in close_in fd_in; line (*end*) with End_of_file -> close_in fd_in; "vide" in Lwt.return (html (head (title (txt "Upload")) []) (body [h1 [txt to_display]]))) let uploadform = Eliom_registration.Html.register upload (fun () () -> let f = (Form.post_form ~service:upload2 (fun file -> [p [Form.file_input ~name:file (); br (); Form.input ~input_type:`Submit ~value:"Send" Form.string ]]) ()) in Lwt.return (html (head (title (txt "form")) []) (body [f]))) ``` ### Raw POST data (advanced use) By specifying `~post_params:Eliom_parameter.raw_post_params`, it is possible to create a service that takes as parameter any POST data, as a stream. The only restriction is that it does not work if the content-type corresponds to URL encoded form data or multipart data (because in these cases, there are POST parameters, which are decoded by Eliom to find the service). See the API reference for more information.