source: wiki/pages/WikiHtml @ 40226

Last change on this file since 40226 was 38413, checked in by obi, 8 years ago

reset wiki

File size: 9.6 KB
Line 
1= Using HTML in Wiki Text =
2
3Trac supports the display of HTML in any wiki context, by using the `#!html` [wiki:WikiProcessors WikiProcessor].
4
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.
7
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.
9
10== How to use `#!html` == #HowtoUseHTML
11To 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
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.
30
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.
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
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.
113
114For 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
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.
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
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.
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 ==
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:
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.