1 | = Using HTML in Wiki Text = |
---|
2 | |
---|
3 | Trac supports the display of HTML in any wiki context, by using the `#!html` [wiki:WikiProcessors WikiProcessor]. |
---|
4 | |
---|
5 | However, this HTML has to be [http://en.wikipedia.org/wiki/Well-formed_element well-formed]. |
---|
6 | In particular, you can't insert a start tag in an `#!html` block, resume normal wiki text and insert the corresponding end tag in a second `#!html` block. |
---|
7 | |
---|
8 | Fortunately, for creating styled <div>s, <span>s or even complex tables containing arbitrary Wiki text, there is a powerful alternative: `#!div`, `#!span` and `#!table`, `#!tr`, `#!td` and `#!th` blocks. Those Wiki processors are built-in and do not require additional packages to be installed. |
---|
9 | |
---|
10 | == How to use `#!html` == #HowtoUseHTML |
---|
11 | To inform the wiki engine that a block of text should be treated as HTML, use the ''html'' processor: |
---|
12 | |
---|
13 | ||= Wiki Markup =||= Display =|| |
---|
14 | {{{#!td |
---|
15 | {{{ |
---|
16 | {{{ |
---|
17 | #!html |
---|
18 | <h1 style="text-align: right; color: blue">HTML Test</h1> |
---|
19 | }}} |
---|
20 | }}} |
---|
21 | }}} |
---|
22 | {{{#!td style="padding-left: 2em" |
---|
23 | {{{ |
---|
24 | #!html |
---|
25 | <h1 style="text-align: right; color: blue">HTML Test</h1> |
---|
26 | }}} |
---|
27 | }}} |
---|
28 | |
---|
29 | Note that Trac sanitizes your HTML code before displaying it. That means that potentially dangerous constructs, such as Javascript event handlers, will be removed from the output. |
---|
30 | |
---|
31 | The filtering is done by [http://genshi.edgewall.org/ Genshi] and the output will be a well-formed fragment of HTML. This means that you can no longer use two HTML blocks, one for opening a <div> and another for closing it, in order to wrap arbitrary wiki text. |
---|
32 | The new way to wrap any wiki content inside a <div> is to use the `#!div` Wiki processor. |
---|
33 | |
---|
34 | == How to use `#!div` and `#!span` == #HowtoUseDivSpan |
---|
35 | |
---|
36 | ||= Wiki Markup =||= Display =|| |
---|
37 | {{{#!td |
---|
38 | {{{ |
---|
39 | {{{ |
---|
40 | #!div class="important" |
---|
41 | **important** is a predefined class. |
---|
42 | }}} |
---|
43 | }}} |
---|
44 | {{{ |
---|
45 | {{{ |
---|
46 | #!div style="border: 1pt dotted; margin: 1em" |
---|
47 | **wikipage** is another predefined class that will |
---|
48 | be used when no class is specified. |
---|
49 | }}} |
---|
50 | }}} |
---|
51 | {{{ |
---|
52 | {{{ |
---|
53 | #!div class="compact" style="border: 1pt dotted; margin: 1em" |
---|
54 | **compact** is another predefined class reducing |
---|
55 | the padding within the `<div>` to a minimum. |
---|
56 | }}} |
---|
57 | }}} |
---|
58 | {{{ |
---|
59 | {{{ |
---|
60 | #!div class="wikipage compact" style="border: 1pt dotted" |
---|
61 | Classes can be combined (here **wikipage** and **compact**) |
---|
62 | which results in this case in reduced //vertical// |
---|
63 | padding but there's still some horizontal space for coping |
---|
64 | with headings. |
---|
65 | }}} |
---|
66 | }}} |
---|
67 | {{{ |
---|
68 | {{{ |
---|
69 | #!div class="" style="border: 1pt dotted; margin: 1em" |
---|
70 | Explicitly specifying no classes is //not// the same |
---|
71 | as specifying no class attribute, as this will remove |
---|
72 | the //wikipage// default class. |
---|
73 | }}} |
---|
74 | }}} |
---|
75 | }}} |
---|
76 | {{{#!td style="padding-left: 2em" |
---|
77 | |
---|
78 | {{{ |
---|
79 | #!div class="important" |
---|
80 | **important** is a predefined class. |
---|
81 | }}} |
---|
82 | |
---|
83 | {{{ |
---|
84 | #!div style="border: 1pt dotted; margin: 1em" |
---|
85 | **wikipage** is another predefined class that will |
---|
86 | be used when no class is specified. |
---|
87 | }}} |
---|
88 | |
---|
89 | {{{ |
---|
90 | #!div class="compact" style="border: 1pt dotted; margin: 1em" |
---|
91 | **compact** is another predefined class reducing |
---|
92 | the padding within the `<div>` to a minimum. |
---|
93 | }}} |
---|
94 | |
---|
95 | {{{ |
---|
96 | #!div class="wikipage compact" style="border: 1pt dotted" |
---|
97 | Classes can be combined (here **wikipage** and **compact**) |
---|
98 | which results in this case in reduced //vertical// |
---|
99 | padding but there's still some horizontal space for coping |
---|
100 | with headings. |
---|
101 | }}} |
---|
102 | |
---|
103 | {{{ |
---|
104 | #!div class="" style="border: 1pt dotted; margin: 1em" |
---|
105 | Explicitly specifying no classes is //not// the same |
---|
106 | as specifying no class attribute, as this will remove |
---|
107 | the //wikipage// default class. |
---|
108 | }}} |
---|
109 | |
---|
110 | }}} |
---|
111 | |
---|
112 | Note that the contents of a `#!div` block are contained in one or more paragraphs, which have a non-zero top and bottom margin. This leads to the top and bottom padding in the example above. To remove the top and bottom margin of the content, add the `compact` class to the `#!div`. Another predefined class besides `wikipage` and `compact` is `important`, which can be used to make a paragraph stand out. Extra CSS classes can be defined via the `site/style.css` file for example, see TracInterfaceCustomization#SiteAppearance. |
---|
113 | |
---|
114 | For spans, you should use the Macro call syntax: |
---|
115 | ||= Wiki Markup =|| |
---|
116 | {{{#!td |
---|
117 | {{{ |
---|
118 | Hello |
---|
119 | [[span(''WORLD'' (click [#anchor here]), style=color: green; font-size: 120%, id=anchor)]]! |
---|
120 | }}} |
---|
121 | }}} |
---|
122 | |--------------------------------------------------------------------------------- |
---|
123 | ||= Display =|| |
---|
124 | {{{#!td style="padding-left: 2em" |
---|
125 | Hello |
---|
126 | [[span(''WORLD'' (click [#anchor here]), style=color: green; font-size: 120%, id=anchor)]]! |
---|
127 | }}} |
---|
128 | |
---|
129 | == How to use `#!td` and other table related processors == #Tables |
---|
130 | |
---|
131 | The `#!td` or `#!th` processors should be used to create table data and table header cells, respectively. The other processors `#!table` and `#!tr` are not required for introducing a table structure, as `#!td` and `#!th` will do this automatically. The `|-` row separator can be used to start a new row when needed, but some may prefer to use a `#!tr` block for that, as this introduces a more formal grouping and offers the possibility to use an extra level of indentation. The main purpose of the `#!table` and `#!tr` is to give the possibility to specify HTML attributes, like ''style'' or ''valign'' to these elements. |
---|
132 | |
---|
133 | ||= Wiki Markup =||= Display =|| |
---|
134 | {{{#!td |
---|
135 | {{{ |
---|
136 | Simple 2x2 table with rich content: |
---|
137 | {{{#!th align=left |
---|
138 | - Left |
---|
139 | - Header |
---|
140 | }}} |
---|
141 | {{{#!th align=left |
---|
142 | - Right |
---|
143 | - Header |
---|
144 | }}} |
---|
145 | |---------------------------------- |
---|
146 | {{{#!td style="background: #ffd" |
---|
147 | - Left |
---|
148 | - Content |
---|
149 | }}} |
---|
150 | {{{#!td style="vertical-align: top" |
---|
151 | !RightContent |
---|
152 | }}} |
---|
153 | |---------------------------------- |
---|
154 | || ... and this can be mixed||\ |
---|
155 | ||with pipe-based cells || |
---|
156 | {{{#!td colspan=2 |
---|
157 | Pick the style the more appropriate |
---|
158 | to your content |
---|
159 | |
---|
160 | See WikiFormatting#Tables for details |
---|
161 | on the pipe-based table syntax. |
---|
162 | }}} |
---|
163 | |
---|
164 | If one needs to add some |
---|
165 | attributes to the table itself... |
---|
166 | |
---|
167 | {{{ |
---|
168 | #!table style="border:none;text-align:center;margin:auto" |
---|
169 | {{{#!tr ==================================== |
---|
170 | {{{#!th style="border: none" |
---|
171 | Left header |
---|
172 | }}} |
---|
173 | {{{#!th style="border: none" |
---|
174 | Right header |
---|
175 | }}} |
---|
176 | }}} |
---|
177 | {{{#!tr ==== style="border: 1px dotted grey" |
---|
178 | {{{#!td style="border: none" |
---|
179 | 1.1 |
---|
180 | }}} |
---|
181 | {{{#!td style="border: none" |
---|
182 | 1.2 |
---|
183 | }}} |
---|
184 | }}} |
---|
185 | {{{#!tr ==================================== |
---|
186 | {{{#!td style="border: none" |
---|
187 | 2.1 |
---|
188 | }}} |
---|
189 | {{{#!td |
---|
190 | 2.2 |
---|
191 | }}} |
---|
192 | }}} |
---|
193 | }}} |
---|
194 | |
---|
195 | |
---|
196 | }}} |
---|
197 | }}} |
---|
198 | {{{#!td valign=top |
---|
199 | Simple 2x2 table with rich content: |
---|
200 | {{{#!th align=left |
---|
201 | - Left |
---|
202 | - Header |
---|
203 | }}} |
---|
204 | {{{#!th align=left |
---|
205 | - Right |
---|
206 | - Header |
---|
207 | }}} |
---|
208 | |---------------------------------- |
---|
209 | {{{#!td style="background: #ffd" |
---|
210 | - Left |
---|
211 | - Content |
---|
212 | }}} |
---|
213 | {{{#!td style="vertical-align: top" |
---|
214 | !RightContent |
---|
215 | }}} |
---|
216 | |---------------------------------- |
---|
217 | || ... and this can be mixed||\ |
---|
218 | ||with pipe-based cells || |
---|
219 | {{{#!td colspan=2 |
---|
220 | Pick the style the more appropriate |
---|
221 | to your content |
---|
222 | |
---|
223 | See WikiFormatting#Tables for details |
---|
224 | on the pipe-based table syntax. |
---|
225 | }}} |
---|
226 | |
---|
227 | If one needs to add some |
---|
228 | attributes to the table itself... |
---|
229 | |
---|
230 | {{{ |
---|
231 | #!table style="border:none;text-align:center;margin:auto" |
---|
232 | {{{#!tr ==================================== |
---|
233 | {{{#!th style="border: none" |
---|
234 | Left header |
---|
235 | }}} |
---|
236 | {{{#!th style="border: none" |
---|
237 | Right header |
---|
238 | }}} |
---|
239 | }}} |
---|
240 | {{{#!tr ==== style="border: 1px dotted grey" |
---|
241 | {{{#!td style="border: none" |
---|
242 | 1.1 |
---|
243 | }}} |
---|
244 | {{{#!td style="border: none" |
---|
245 | 1.2 |
---|
246 | }}} |
---|
247 | }}} |
---|
248 | {{{#!tr ==================================== |
---|
249 | {{{#!td style="border: none" |
---|
250 | 2.1 |
---|
251 | }}} |
---|
252 | {{{#!td |
---|
253 | 2.2 |
---|
254 | }}} |
---|
255 | }}} |
---|
256 | }}} |
---|
257 | }}} |
---|
258 | |
---|
259 | Note that by default tables are assigned the "wiki" CSS class, which gives a distinctive look to the header cells and a default border to the table and cells, as can be seen for the tables on this page. By removing this class (`#!table class=""`), one regains complete control on the table presentation. In particular, neither the table nor the rows nor the cells will have a border, so this is a more effective way to get such an effect rather than having to specify a `style="border: no"` parameter everywhere. |
---|
260 | |
---|
261 | {{{#!table class="" |
---|
262 | ||= Wiki Markup =||= Display =|| |
---|
263 | {{{#!td |
---|
264 | {{{ |
---|
265 | {{{#!table class="" |
---|
266 | || 0|| 1|| 2|| |
---|
267 | || 10|| 20|| 30|| |
---|
268 | || 11|| 22|| 33|| |
---|
269 | ||||||= numbers =|| |
---|
270 | }}} |
---|
271 | }}} |
---|
272 | }}} |
---|
273 | {{{#!td |
---|
274 | {{{#!table class="" |
---|
275 | || 0|| 1|| 2|| |
---|
276 | || 10|| 20|| 30|| |
---|
277 | || 11|| 22|| 33|| |
---|
278 | ||||||= numbers =|| |
---|
279 | }}} |
---|
280 | }}} |
---|
281 | }}} |
---|
282 | |
---|
283 | Other classes can be specified as alternatives (remember that you can define your own in [TracInterfaceCustomization#SiteAppearance site/style.css]). |
---|
284 | |
---|
285 | ||= Wiki Markup =||= Display =|| |
---|
286 | {{{#!td |
---|
287 | {{{ |
---|
288 | {{{#!table class="listing" |
---|
289 | || 0|| 1|| 2|| |
---|
290 | || 10|| 20|| 30|| |
---|
291 | || 11|| 22|| 33|| |
---|
292 | ||||||= numbers =|| |
---|
293 | }}} |
---|
294 | }}} |
---|
295 | }}} |
---|
296 | {{{#!td |
---|
297 | {{{#!table class="listing" |
---|
298 | || 0|| 1|| 2|| |
---|
299 | || 10|| 20|| 30|| |
---|
300 | || 11|| 22|| 33|| |
---|
301 | ||||||= numbers =|| |
---|
302 | }}} |
---|
303 | }}} |
---|
304 | |
---|
305 | == HTML comments == |
---|
306 | HTML comments are stripped from the output of the `html` processor. To add an HTML comment to a wiki page, use the `htmlcomment` processor, available since Trac 0.12: |
---|
307 | ||= Wiki Markup =|| |
---|
308 | {{{#!td |
---|
309 | {{{ |
---|
310 | {{{ |
---|
311 | #!htmlcomment |
---|
312 | This block is translated to an HTML comment. |
---|
313 | It can contain <tags> and &entities; that will not be escaped in the output. |
---|
314 | }}} |
---|
315 | }}} |
---|
316 | }}} |
---|
317 | |--------------------------------------------------------------------------------- |
---|
318 | ||= Display =|| |
---|
319 | {{{#!td |
---|
320 | {{{ |
---|
321 | <!-- |
---|
322 | This block is translated to an HTML comment. |
---|
323 | It can contain <tags> and &entities; that will not be escaped in the output. |
---|
324 | --> |
---|
325 | }}} |
---|
326 | }}} |
---|
327 | |
---|
328 | Please note that the character sequence "`--`" is not allowed in HTML comments, and will generate a rendering error. |
---|
329 | |
---|
330 | |
---|
331 | == More Information == |
---|
332 | |
---|
333 | * http://www.w3.org/ -- World Wide Web Consortium |
---|
334 | * http://www.w3.org/MarkUp/ -- HTML Markup Home Page |
---|
335 | |
---|
336 | ---- |
---|
337 | See also: WikiProcessors, WikiFormatting, WikiRestructuredText |
---|