Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 124 lines (97 sloc) 4.369 kb
ecdaf738 »
2012-11-24 Initial README file
1 #+title: X-HTML-TEMPLATE Library
9a6e4dd1 »
2012-11-24 Make up the README a bit
2 #+startup: showall content
ecdaf738 »
2012-11-24 Initial README file
3
9a6e4dd1 »
2012-11-24 Make up the README a bit
4 * X-HTML-TEMPLATE Library
5
6 ** Introduction
7 /X-HTML-TEMPLATE/ library is a little fork of the Common Lisp library
ecdaf738 »
2012-11-24 Initial README file
8 [[http://weitz.de/html-template/][html-template]] which adds support for computed expressions while keeps
5cee4935 »
2012-11-24 More changes to the README
9 mostly compatible. See the differences with /html-template/ [[Differences with html-template][below]].
ecdaf738 »
2012-11-24 Initial README file
10
5cee4935 »
2012-11-24 More changes to the README
11 I wrote this because we were using too many html-templates and
ecdaf738 »
2012-11-24 Initial README file
12 migrating to a new template system was not worth. We wanted some extra
13 flexibility however and it made our lives easier.
14
9a6e4dd1 »
2012-11-24 Make up the README a bit
15 ** Using x-html-template
16 The /HTML-TEMPLATE/ API is untouched (see its documentation if you are
5cee4935 »
2012-11-24 More changes to the README
17 not used /HTML-TEMPLATE/ before), except the system name and packages
9a6e4dd1 »
2012-11-24 Make up the README a bit
18 were renamed to /X-HTML-TEMPLATE/, to avoid possible collisions. A
ecdaf738 »
2012-11-24 Initial README file
19 package nickname =x-template= is also provided as shortcut.
20
9a6e4dd1 »
2012-11-24 Make up the README a bit
21 /X-HTML-TEMPLATE/ changes the semantic of the template attributes. The
ecdaf738 »
2012-11-24 Initial README file
22 tags accept expressions instead of symbols. The expressions follow the following syntax:
23
b52d1196 »
2012-11-24 Use upper case blocks to make github happy
24 #+BEGIN_EXAMPLE
ecdaf738 »
2012-11-24 Initial README file
25 expression ::= 'literal'
26 | "literal"
27 | symbol
28 | symbol(expression_1,expression_2,..,expression_N)
b52d1196 »
2012-11-24 Use upper case blocks to make github happy
29 #+END_EXAMPLE
ecdaf738 »
2012-11-24 Initial README file
30
31 A hypothetical template could look like
32
33 #+BEGIN_EXAMPLE
34 <!-- tmpl_loop sort(users,'name') -->
9a6e4dd1 »
2012-11-24 Make up the README a bit
35 <!-- tmpl_var escape-html(upcase(name)) -->
ecdaf738 »
2012-11-24 Initial README file
36 <!-- /tmpl_if -->
37 <!-- /tmpl_loop -->
38 #+END_EXAMPLE
39
5cee4935 »
2012-11-24 More changes to the README
40 This change diverges from the philosophy of /HTML-TEMPLATE/ about
ecdaf738 »
2012-11-24 Initial README file
41 separation of the code and the layout. However, this library does not
42 provide harmful abstractions itself, but it offers the ability to
43 provide them :-)
44
45 I really think that used properly, the extensions can be useful.
46
9a6e4dd1 »
2012-11-24 Make up the README a bit
47 ** Examples
ecdaf738 »
2012-11-24 Initial README file
48
5cee4935 »
2012-11-24 More changes to the README
49 A simple use:
50
b52d1196 »
2012-11-24 Use upper case blocks to make github happy
51 #+BEGIN_SRC common-lisp
ecdaf738 »
2012-11-24 Initial README file
52 (with-output-to-string (*default-template-output*)
53 (fill-and-print-template
54 "<!-- tmpl_var html-escape(string) -->"
9a6e4dd1 »
2012-11-24 Make up the README a bit
55 (list :string "0 <> 1" :html-escape #'escape-string-all)))
b52d1196 »
2012-11-24 Use upper case blocks to make github happy
56 #+END_SRC
ecdaf738 »
2012-11-24 Initial README file
57 =>
b52d1196 »
2012-11-24 Use upper case blocks to make github happy
58 #+BEGIN_EXAMPLE
ecdaf738 »
2012-11-24 Initial README file
59 "0 &amp;lt;&amp;gt; 1"
b52d1196 »
2012-11-24 Use upper case blocks to make github happy
60 #+END_EXAMPLE
ecdaf738 »
2012-11-24 Initial README file
61
9a6e4dd1 »
2012-11-24 Make up the README a bit
62 *** Providing a default set of user-defined functions
ecdaf738 »
2012-11-24 Initial README file
63 Sometimes, it is convenient to provide a default set of user-defined
64 function values to the templates. You can set the special variable
65 =*VALUE-ACCESS-FUNCTION*= to provide them. The code would look like:
66
b52d1196 »
2012-11-24 Use upper case blocks to make github happy
67 #+BEGIN_SRC common-lisp
ecdaf738 »
2012-11-24 Initial README file
68 (defvar *x-template-default-values*
69 (list :html-escape #'escape-string-all))
70
71 (unless (boundp '*original-value-access-function*)
72 (defvar *original-value-access-function*
73 ,*value-access-function*))
74
75 (setf *value-access-function*
76 (lambda (symbol values &optional in-loop)
77 (or (funcall *original-value-access-function* symbol values in-loop)
78 (getf *x-template-default-values* symbol))))
b52d1196 »
2012-11-24 Use upper case blocks to make github happy
79 #+END_SRC
ecdaf738 »
2012-11-24 Initial README file
80
81 Then, we can write the above example without defining the html-escape
82 function.
b52d1196 »
2012-11-24 Use upper case blocks to make github happy
83 #+BEGIN_SRC common-lisp
ecdaf738 »
2012-11-24 Initial README file
84 (with-output-to-string (*default-template-output*)
85 (fill-and-print-template
86 "<!-- tmpl_var html-escape(string) -->"
87 (list :string "0 <> 1")))
88 #+END_SRC
89
90
9a6e4dd1 »
2012-11-24 Make up the README a bit
91 ** Differences with html-template
5cee4935 »
2012-11-24 More changes to the README
92 /X-HTML-TEMPLATE/ is not fully compatible with /HTML-TEMPLATE/, but it
93 is in the common cases and porting your code should be trivial.
ecdaf738 »
2012-11-24 Initial README file
94
9a6e4dd1 »
2012-11-24 Make up the README a bit
95 *** Quoting attributes
5cee4935 »
2012-11-24 More changes to the README
96 /HTML-TEMPLATE/ allows to quote an attribute as =<!-- tmpl_var 'foobar' -->=
9a6e4dd1 »
2012-11-24 Make up the README a bit
97 As 'foobar' is a literal string in /X-HTML-TEMPLATE/, this code will not
ecdaf738 »
2012-11-24 Initial README file
98 work in the same way. To port it, just remove the single or double
9a6e4dd1 »
2012-11-24 Make up the README a bit
99 quotes. However, if you are quoting the symbol because it contains
100 spaces or non-allowed characters, then you will have to rename your
101 symbol.
ecdaf738 »
2012-11-24 Initial README file
102
9a6e4dd1 »
2012-11-24 Make up the README a bit
103 *** White-spaces delimiters
ecdaf738 »
2012-11-24 Initial README file
104
5cee4935 »
2012-11-24 More changes to the README
105 /HTML-TEMPLATE/ white-spaces delimiters after the template start
106 marker are optional and you could omit them if you quote the
107 parameters. In /X-HTML-TEMPLATE/, quoting parameters is not allowed,
108 but the white-spaces are optional anyway.
ecdaf738 »
2012-11-24 Initial README file
109
9a6e4dd1 »
2012-11-24 Make up the README a bit
110 Therefore, a template like =<!-- tmpl_var foo-->= which is *not* legal
5cee4935 »
2012-11-24 More changes to the README
111 in /HTML-TEMPLATE/, will be in /X-HTML-TEMPLATE/. It could seem weird,
112 but it becomes useful if you override the default tag
113 markers. Consider, for example:
ecdaf738 »
2012-11-24 Initial README file
114
9a6e4dd1 »
2012-11-24 Make up the README a bit
115 =<tmpl_var foo>= in contrast to =<tmpl_var foo >=.
ecdaf738 »
2012-11-24 Initial README file
116
9a6e4dd1 »
2012-11-24 Make up the README a bit
117 A full working example:
ecdaf738 »
2012-11-24 Initial README file
118
119 #+BEGIN_SRC common-lisp
946d525d »
2012-11-24 Remove package prefix of the last example
120 (let ((*template-start-marker* "<")
121 (*template-end-marker* ">"))
122 (with-output-to-string (*default-template-output*)
ecdaf738 »
2012-11-24 Initial README file
123 (x-template:fill-and-print-template "<tmpl_var foo>" '(:foo "bar"))))
124 #+END_SRC
Something went wrong with that request. Please try again.