html-template: HTML-Writing Template Language for SXML/xexp in Racket
(require (planet neil/html-template:2:2)) |
1 Introduction
(define (write-essay my-title) (html-template (html (head (title (% my-title))) (body (h1 (% my-title)) (p "Kittens claw." (br) "Puppies pee."))))) (write-essay "All About Kittens & Puppies")
<html><head><title>All About Kittens & Puppies</title></head><body><h1>All About Kittens & Puppies</h1><p>Kittens claw.<br>Puppies pee.</p></body></html>
(let-values (((out) (current-output-port))) (parameterize ((current-output-port html-template-error-catching-output-port)) (write-bytes #"<html><head><title>" out) (%html-template:format/content/write my-title out) (write-bytes #"</title></head><body><h1>" out) (%html-template:format/content/write my-title out) (write-bytes #"</h1><p>Kittens claw.<br>Puppies pee.</p></body></html>" out) (void)))
(html-template (html (h1 "People") (p "The people are:") (table (@ (border "1")) (tr (th "Name") (th "Color")) (%write (for-each (lambda (person) (html-template (tr (td (% (person-name person))) (td (% (person-color person)))))) people))) (p "Fin.")))
<html><h1>People</h1><p>The people are:</p><table border="1"><tr><th>Name</th><th>Color</th></tr><tr><td>Juliette</td><td>Blue</td></tr><tr><td>Zbigniew</td><td>White</td></tr><tr><td>Irene</td><td>Red</td></tr></table><p>Fin.</p></html>
2 Interface
syntax
maybe-port =
| #:port output-port-or-false content-context = element | string? | bytes? | escape element-context = element | escape element = (symbol? maybe-attributes content-context ...) maybe-attributes =
| (@ attribute-context ...+) attribute-context = attribute | escape-except-format attribute = (symbol? attribute-value-context ...+) attribute-value-context = string? | bytes? | escape escape = escape-except-format | (%format expr ...+) | (% expr ...+) escape-except-format = (%verbatim expr ...+) | (%write expr ...+) | (%write/port var expr ...+) | (%void expr ...+)
(%xexp expr ...) and (%sxml expr ...) —
expr evaluates to an SXML/xexp value, which is output as HTML in the appropriate context (e.g., content context vs. attribute value context). (%format expr ...) and (% expr ...) —
expr evaluates to some value, and this value is formatted for appropriate literal display in HTML. For example, a string value is displayed as text, an integer value is displayed as a number, a date object is displayed as a date, etc. The formatting handler is customizable by the application programmer. (Note that the meaning of % changed purposes in PLaneT version 2:0 of this package: in version 1:1, it was similar to the current %xexp, rather than being shorthand for %format. (%verbatim expr ...) —
expr evaluates to bytes, string, or a list of byteses and/or strings, which are output verbatim as bytes. (%write expr ...) —
expr is evaluated, and any writes to current-output-port are added verbatim to the output. Note that %write and %write/port are the only template escapes that permit writing directly to a port that goes to HTML output. (%write/port var expr ...) —
Like %write, except that writing must be to the output port var. Writing to current-output-port within %write/var will raise an error, on the assumption that it’s most likely a bug (like a missing port parameter in a display, printf, or nested html-template). (%void expr ...) —
expr is evaluated, and any value is ignored. This is used for side-effects.
3 History
- PLaneT 2:2 —
2012-09-24 To avoid some runtime errors, a few places in template parsing that did syntax-e were changed to do syntax->list.
- PLaneT 2:1 —
2012-09-12 Element and attribute names can now contain minus and underscore characters.
Commented-out some log-debug uses.
- PLaneT 2:0 —
2012-06-12 Heavy API changes, including changing all the template escapes.
Heavy internal changes, to enable optimizations in the forthcoming web-server-xexp package.
Much more testing.
Converted to use McFly and Overeasy.
- Version 0.2 —
PLaneT 1:1 — 2011-08-22 Added % as alias for %eval.
- Version 0.1 —
PLaneT 1:0 — 2011-08-21 Initial release.
4 Legal
Copyright 2011 – 2012 Neil Van Dyke. This program is Free Software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See http://www.gnu.org/licenses/ for details. For other licenses and consulting, please contact the author.