Changes between Version 1 and Version 2 of WikiHtml


Ignore:
Timestamp:
Jul 17, 2008 10:45:00 AM (12 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiHtml

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