source: wiki/pages/WikiHtml @ 37371

Last change on this file since 37371 was 37343, checked in by aafsvn, 8 years ago

[titan] autoupdate wiki files

File size: 9.6 KB
RevLine 
[26484]1= Using HTML in Wiki Text =
2
[37343]3Trac supports the display of HTML in any wiki context, by using the `#!html` [wiki:WikiProcessors WikiProcessor].
[26484]4
[37343]5However, this HTML has to be [http://en.wikipedia.org/wiki/Well-formed_element well-formed].
6In 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.
[26484]7
[37343]8Fortunately, 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.
[26484]9
10== How to use `#!html` == #HowtoUseHTML
[37343]11To inform the wiki engine that a block of text should be treated as HTML, use the ''html'' processor:
[26484]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
[37343]29Note 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.
[26484]30
[37343]31The 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.
32The new way to wrap any wiki content inside a <div> is to use the `#!div` Wiki processor.
[26484]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
[37343]112Note 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.
[26484]113
[37343]114For spans, you should use the Macro call syntax:
[26484]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
[37343]131The `#!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.
[26484]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
199Simple 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
220Pick the style the more appropriate
221to your content
222
223See WikiFormatting#Tables for details
224on the pipe-based table syntax.
225}}}
226
227If one needs to add some
228attributes 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
[37343]259Note 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.
[26484]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
283Other 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 ==
[37343]306HTML 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:
[26484]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
328Please 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----
337See also:  WikiProcessors, WikiFormatting, WikiRestructuredText
Note: See TracBrowser for help on using the repository browser.