ikiwiki (3.20130711) unstable; urgency=low
[ikiwiki.git] / doc / bugs / template_creation_error.mdwn
1 Hi,
2 I am trying to build a template. The compilation of this template results in a weird exception. I have isolated the cause of the exception to the following point:
3
4 If i have this in the template code:
5
6 \[[!inline<br/>
7 pages="\<TMPL_VAR SEL_PAGES\>"<br/>
8 template=extract-entry<br/>
9 \]]<br/>
10
11 There is no problem at all. I can use the template with the desired result. But if I try to use this (just adding the "show" parameter):
12
13 \[[!inline <br/>
14 pages="\<TMPL_VAR SEL_PAGES>"<br/>
15 template=extract-entry<br/>
16 show=\<TMPL_VAR CNTPG><br/>
17 \]]<br/>
18
19 I get this exception on the Git bash console:
20
21 <pre>
22 $ git push
23 Counting objects: 7, done.
24 Delta compression using up to 8 threads.
25 Compressing objects: 100% (4/4), done.
26 Writing objects: 100% (4/4), 410 bytes, done.
27 Total 4 (delta 3), reused 0 (delta 0)
28 remote: From /home/b-odelama-com/source
29 remote:    eb1421e..5e1bac5  master     -> origin/master
30 remote: Argument "\x{3c}\x{54}..." isn't numeric in numeric lt (<) at /usr/share/perl5/IkiWiki/Plugin/inline.pm line 231.
31 remote: Argument "\x{3c}\x{54}..." isn't numeric in numeric lt (<) at /usr/share/perl5/IkiWiki/Plugin/inline.pm line 231.
32 To ssh://b-odelama-com@odelama-com.branchable.com/
33    eb1421e..5e1bac5  master -> master
34 </pre>
35
36 Please, let me know what to do to avoid this kind of error.
37
38 > When you add a template page `templates/foo.mdwn` for use
39 > the [[ikiwiki/directive/template]] directive, two things happen:
40 >
41 > 1. `\[[!template id=foo ...]]` becomes available;
42 > 2. a wiki page `templates/foo` is built, resulting in a HTML file,
43 >    typically `templates/foo/index.html`
44 >
45 > The warnings you're seeing are the second of these: when ikiwiki
46 > tries to process `templates/foo.mdwn` as an ordinary page, without
47 > interpreting the `<TMPL_VAR>` directives, `inline` receives invalid
48 > input.
49 >
50 > This is a bit of a design flaw in [[plugins/template]] and
51 > [[plugins/edittemplate]], I think - ideally it would be possible to
52 > avoid parts of the page being interpreted when the page is being
53 > rendered normally rather than being used as a template.
54 >
55 > There *is* a trick to avoid parts of the page being interpreted when
56 > the page is being used as a template, while having them appear
57 > when it's rendered as a page:
58 >
59 >     <TMPL_IF FALSE>
60 >     <!-- This part only appears when being used as a page.
61 >          It assumes that you never set FALSE to a true value :-) -->
62 >     \[[!meta robots="noindex,nofollow"]]
63 >     This template is used to describe a thing. Parameters:
64 >     * name: the name of the thing
65 >     * size: the size of the thing
66 >     </TMPL_IF>
67 >
68 >     The thing is called <TMPL_VAR name> and its size is <TMPL_VAR size>
69 >
70 > I suppose you could maybe extend that to something like this:
71 >
72 >     <TMPL_IF FALSE>
73 >     <!-- This part only appears when being used as a page.
74 >          It assumes that you never set FALSE to a true value :-) -->
75 >     \[[!meta robots="noindex,nofollow"]]
76 >     This template is used to describe a thing. Parameters:
77 >     * name: the name of the thing
78 >     * size: the size of the thing
79 >     </TMPL_IF>
80 >
81 >     <TMPL_IF FALSE>
82 >     \[[!if test="included() and !included()" then="""
83 >     </TMPL_IF>
84 >     <!-- This part only appears when being used as a template. It also
85 >          assumes that you never set FALSE to a true value, and it
86 >          relies on the [[ikiwiki/pagespec]] "included() and !included()"
87 >          never being true. -->
88 >     The thing is called <TMPL_VAR name> and its size is <TMPL_VAR size>
89 >     <TMPL_IF FALSE>
90 >     """]]
91 >     </TMPL_IF>
92 >
93 > but that's far harder than it ought to be!
94 >
95 > Perhaps the right solution would be to change how the template plugin
96 > works, so that templates are expected to contain a new `definetemplate`
97 > directive:
98 >
99 >     This template is used to describe a thing. Parameters:
100 >     * name: the name of the thing
101 >     * size: the size of the thing
102 >     
103 >     \[[!definetemplate """
104 >     The thing is called <TMPL_VAR name> and its size is <TMPL_VAR size>
105 >     """]]
106 >
107 > with templates not containing a `\[[!definetemplate]]` being treated
108 > as if the whole text of the page was copied into a `\[[!definetemplate]]`,
109 > for backwards compatibility?
110 >
111 > --[[smcv]]