Reference manual
Version 1.3.0
- Lwt
- Lwt API reference
- Eliom
- Main modules
- Pages with Ocamlduce
- XHTML pages typed with variants
- Other pages
- Creating new kinds of pages
- Ocsigen
This is a preliminary version of the documentation. Help us to improve it by filling tickets. We are looking for native english speakers to proof read the documentation. Contact us!
Ocsigen provides several ways to generate and type xhtml pages.
- The most powerfull is the typing of pages with OcamlDuce. To take benefit of it, use OCamlDuce instead of OCaml.
- If you don't want OCamlduce, you can use the XHTML.M module, by Thorsten Ohl, that provides a typing based on OCaml's polymorphic variants.
- It is also possible to use a syntax extension to write your pages with the usual xhtml syntax. This solution is also typed with polymorphic variants ans is compatible with the previous one.
- You can also choose to generate untyped xhtml as text.
OCamlduce
OCaml's type system is not powerfull enough to type XML. OCamlduce manual says: "The goal of the OCamlDuce project is to extend the OCaml language with features to make it easier to write safe and efficient complex applications that need to deal with XML documents. In particular, it relies on a notion of types and patterns to guarantee statically that all the possible input documents are correctly processed, and that only valid output documents are produced."
OCamlduce is exactly what we need to type our pages. We recommand its use, even if Eliom's tutorial is written with XHTML.M (for historical reasons). The full documentation is available from here.
XHTML.M
The types in OCaml closest to XML types are polymorphic variants. Thorsten Ohl wrote a module providing very good xhtml typing based on them. The full documentation is available here.
Xhtml syntax extension
Ocsigen has a syntax extension for OCaml that enables to writes pages using html syntax (even if you can do without). Use it for example if you want to include (parts of) html pages that have already been created. This syntax extension uses the same polymorphic variants as XHTML.M, thus this solution can be mixed with the previous one.
For example, the following code:
<< <html>
<head><title></title></head>
<body><h1>plop</h1></body>
</html> >>
is a caml value of type Xhtmltypes.xhtml XHTML.M.elt.
To compile a module containing this syntax, you need the camlp4 preprocessor:
ocamlc -I /path_to/ocsigen/ -pp "camlp4o /path_to/ocsigen/xhtmlsyntax.cma -loc loc" -c your_module.ml
You can insert OCaml expressions of type 'a XHTML.M.elt inside html using $...$, like this:
let oc = << <em>Ocsigen</em> >> in << <p>$oc$ will revolutionize web programming.</p> >>
You can insert OCaml expressions of type string inside html using $str:... $, like this:
let i = 4 in << <p>i is equal to $str:string_of_int i$</p> >>
If you want to use a dollar in your page, just write it twice.
You can write a list of xhtml expressions using the syntax <:xmllist<...>>, for example:
<:xmllist< <p>hello</p> <div></div> >>
Here are some other examples showing what you can do:
<< <ul class=$ulclass$ $list:other_attrs$>
$first_il$
$list:items$
</ul> >>
Warning: lists antiquotations are allowed only at the end (before a closing tag). For example, the following is not valid:
<< <ul $list:other_attrs$ class=$ulclass$>
$list:items$
$last_il$
</ul> >>
The syntax extension is not allowed in patterns for the while.
See other examples in the tutorial.
Text XHTML
The last possibility is to use untyped xhtml. Just build strings containing your pages. Have a look at one example here.
.
