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