Changes between Version 4 and Version 5 of WikiHtml


Ignore:
Timestamp:
Apr 6, 2012 4:33:18 PM (6 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiHtml

    v4 v5  
    11= Using HTML in Wiki Text =
    22
    3 Trac supports inserting HTML into any wiki context, accomplished using the HTML [wiki:WikiProcessors WikiProcessor].
    4 
    5 HTML support is built-in, and does not require installing any additional packages.
    6 
    7 == How to Use HTML ==
     3Trac supports inserting HTML into any wiki context, accomplished using the `#!html` [wiki:WikiProcessors WikiProcessor].
     4
     5However a constraint is that this HTML has to be well-formed.
     6In particular you can't insert a start tag in an `#!html` block,
     7resume normal wiki text and insert the corresponding end tag in a
     8second `#!html` block.
     9
     10Fortunately, for creating styled <div>s, <span>s  or even complex tables
     11containing arbitrary Wiki text, there's a powerful alternative: use of
     12dedicated `#!div`, `#!span` and `#!table`, `#!tr`, `#!td` and `#!th` blocks.
     13
     14Those Wiki processors are built-in, and does not require installing any additional packages.
     15
     16== How to use `#!html` == #HowtoUseHTML
    817To inform the wiki engine that a block of text should be treated as HTML, use the ''html'' processor.
    918
    10 This 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>
    17 }}}
    18 
    19 Results in:
    20 {{{
    21 #!html
    22 <h1 style="text-align: right; color: blue">HTML Test</h1>
     19||= Wiki Markup =||= Display =||
     20{{{
     21#!td
     22  {{{
     23  {{{
     24  #!html
     25  <h1 style="text-align: right; color: blue">HTML Test</h1>
     26 
     27}}}
     28 
     29}}}
     30}}}
     31{{{
     32#!td style="padding-left: 2em"
     33  {{{
     34  #!html
     35  <h1 style="text-align: right; color: blue">HTML Test</h1>
     36 
     37}}}
    2338}}}
    2439
    2540Note 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.
    2641
    27 Since 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.
    28 To achieve this, you need now to use the ''div'' Wiki processor:
    29 
    30 {{{
    31 {{{
    32 #!div class=important style="border: 2pt solid; text-align: center"
    33 This is the ''only'' way to go in Trac 0.11
    34 }}}
    35 }}}
    36 
    37 Results in:
    38 {{{
    39 #!div class=important style="border: 2pt solid; text-align: center"
    40 This is the ''only'' way to go in Trac 0.11
    41 }}}
     42Since 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.
     43The new way to wrap any wiki content inside a <div> is to use the `#!div` Wiki  processor.
     44
     45== How to use `#!div` and `#!span` == #HowtoUseDivSpan
     46
     47||= Wiki Markup =||= Display =||
     48{{{
     49#!td
     50  {{{
     51  {{{
     52  #!div class="important" style="border: 2pt solid; text-align: center"
     53  This is the ''only'' way to go in Trac 0.11
     54 
     55}}}
     56
     57  {{{
     58  #!div class="wikipage" style="border: 1pt dotted"
     59  Only `wikipage` (same as specifying no class attribute)
     60 
     61}}}
     62
     63  {{{
     64  #!div class="wikipage compact " style="border: 1pt solid"
     65  Use combined classes (`compact` and `wikipage`)
     66 
     67}}}
     68
     69  {{{
     70  #!div class="compact" style="border: 1pt dotted"
     71  Only `compact`
     72 
     73}}}
     74
     75  {{{
     76  #!div class="" style="border: 1pt solid"
     77  No classes (//not// the same as specifying no class attribute...)
     78 
     79}}}
     80 
     81}}}
     82}}}
     83{{{
     84#!td style="padding-left: 2em"
     85  {{{
     86  #!div class="important" style="border: 2pt solid; text-align: center"
     87  This is the ''only'' way to go in Trac 0.11
     88 
     89}}}
     90
     91  {{{
     92  #!div class="wikipage" style="border: 1pt dotted"
     93  Only `wikipage` (same as specifying no class attribute)
     94 
     95}}}
     96
     97  {{{
     98  #!div class="wikipage compact " style="border: 1pt solid"
     99  Use combined classes (`compact` and `wikipage`)
     100 
     101}}}
     102
     103  {{{
     104  #!div class="compact" style="border: 1pt dotted"
     105  Only compact
     106 
     107}}}
     108
     109  {{{
     110  #!div class="" style="border: 1pt solid"
     111  No classes (//not// the same as specifying no class attribute...)
     112 
     113}}}
     114}}}
     115
     116Note 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.
    42117
    43118For 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)]]!
    46 }}}
    47 
    48 Results in:
    49  Hello [[span(''WORLD'' (click [#world-anchor here]), style=color: green; font-size: 120%, id=world-anchor)]]!
     119||= Wiki Markup =||
     120{{{
     121#!td
     122  {{{
     123  Hello
     124  [[span(''WORLD'' (click [#anchor here]), style=color: green; font-size: 120%, id=anchor)]]!
     125 
     126}}}
     127}}}
     128|---------------------------------------------------------------------------------
     129||= Display =||
     130{{{
     131#!td style="padding-left: 2em"
     132  Hello
     133  [[span(''WORLD'' (click [#anchor here]), style=color: green; font-size: 120%, id=anchor)]]!
     134}}}
     135
     136== How to use `#!td` and other table related processors == #Tables
     137
     138`#!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.
     139
     140||= Wiki Markup =||= Display =||
     141{{{
     142#!td
     143 {{{
     144 Simple 2x2 table with rich content:
     145 {{{
     146#!th align=left
     147  - Left
     148  - Header
     149 
     150}}}
     151 {{{
     152#!th align=left
     153  - Right
     154  - Header
     155 
     156}}}
     157 |----------------------------------
     158 {{{
     159#!td style="background: #ffd"
     160  - Left
     161  - Content
     162 
     163}}}
     164 {{{
     165#!td style="vertical-align: top"
     166 !RightContent
     167 
     168}}}
     169 |----------------------------------
     170 || ... and this can be mixed||\
     171 ||with pipe-based cells ||
     172 {{{
     173#!td colspan=2
     174 Pick the style the more appropriate
     175 to your content
     176 
     177 See WikiFormatting#Tables for details
     178 on the pipe-based table syntax.
     179 
     180}}}
     181 
     182 If one needs to add some
     183 attributes to the table itself...
     184 
     185 {{{
     186 #!table style="border:none;text-align:center;margin:auto"
     187   {{{
     188#!tr ====================================
     189     {{{
     190#!th style="border: none"
     191     Left header
     192     
     193}}}
     194     {{{
     195#!th style="border: none"
     196     Right header
     197     
     198}}}
     199   
     200}}}
     201   {{{
     202#!tr ==== style="border: 1px dotted grey"
     203     {{{
     204#!td style="border: none"
     205     1.1
     206     
     207}}}
     208     {{{
     209#!td style="border: none"
     210     1.2
     211     
     212}}}
     213   
     214}}}
     215   {{{
     216#!tr ====================================
     217     {{{
     218#!td style="border: none"
     219     2.1
     220     
     221}}}
     222     {{{
     223#!td
     224     2.2
     225     
     226}}}
     227   
     228}}}
     229 
     230}}}
     231
     232
     233 
     234}}}
     235}}}
     236{{{
     237#!td valign=top
     238Simple 2x2 table with rich content:
     239{{{
     240#!th align=left
     241 - Left
     242 - Header
     243}}}
     244{{{
     245#!th align=left
     246 - Right
     247 - Header
     248}}}
     249|----------------------------------
     250{{{
     251#!td style="background: #ffd"
     252 - Left
     253 - Content
     254}}}
     255{{{
     256#!td style="vertical-align: top"
     257!RightContent
     258}}}
     259|----------------------------------
     260|| ... and this can be mixed||\
     261||with pipe-based cells ||
     262{{{
     263#!td colspan=2
     264Pick the style the more appropriate
     265to your content
     266
     267See WikiFormatting#Tables for details
     268on the pipe-based table syntax.
     269}}}
     270
     271If one needs to add some
     272attributes to the table itself...
     273
     274{{{
     275#!table style="border:none;text-align:center;margin:auto"
     276  {{{
     277#!tr ====================================
     278    {{{
     279#!th style="border: none"
     280    Left header
     281   
     282}}}
     283    {{{
     284#!th style="border: none"
     285    Right header
     286   
     287}}}
     288 
     289}}}
     290  {{{
     291#!tr ==== style="border: 1px dotted grey"
     292    {{{
     293#!td style="border: none"
     294    1.1
     295   
     296}}}
     297    {{{
     298#!td style="border: none"
     299    1.2
     300   
     301}}}
     302 
     303}}}
     304  {{{
     305#!tr ====================================
     306    {{{
     307#!td style="border: none"
     308    2.1
     309   
     310}}}
     311    {{{
     312#!td
     313    2.2
     314   
     315}}}
     316 
     317}}}
     318}}}
     319}}}
     320
     321Note 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.
     322
     323{{{
     324#!table class=""
     325||= Wiki Markup =||= Display =||
     326 {{{
     327#!td
     328  {{{
     329  {{{
     330#!table class=""
     331  ||  0||  1||  2||
     332  || 10|| 20|| 30||
     333  || 11|| 22|| 33||
     334  ||||||=  numbers  =||
     335 
     336}}}
     337 
     338}}}
     339 
     340}}}
     341 {{{
     342#!td
     343  {{{
     344#!table class=""
     345  ||  0||  1||  2||
     346  || 10|| 20|| 30||
     347  || 11|| 22|| 33||
     348  ||||||=  numbers  =||
     349 
     350}}}
     351 
     352}}}
     353}}}
     354
     355Other classes can be specified as alternatives (remember that you can define your own in [TracInterfaceCustomization#SiteAppearance site/style.css]).
     356
     357||= Wiki Markup =||= Display =||
     358{{{
     359#!td
     360  {{{
     361  {{{
     362#!table class="listing"
     363  ||  0||  1||  2||
     364  || 10|| 20|| 30||
     365  || 11|| 22|| 33||
     366  ||||||=  numbers  =||
     367 
     368}}}
     369 
     370}}}
     371}}}
     372{{{
     373#!td
     374  {{{
     375#!table class="listing"
     376  ||  0||  1||  2||
     377  || 10|| 20|| 30||
     378  || 11|| 22|| 33||
     379  ||||||=  numbers  =||
     380 
     381}}}
     382}}}
     383
     384
     385== HTML comments ==
     386HTML 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:
     387||= Wiki Markup =||
     388{{{
     389#!td
     390  {{{
     391  {{{
     392  #!htmlcomment
     393  This block is translated to an HTML comment.
     394  It can contain <tags> and &entities; that will not be escaped in the output.
     395 
     396}}}
     397 
     398}}}
     399}}}
     400|---------------------------------------------------------------------------------
     401||= Display =||
     402{{{
     403#!td
     404  {{{
     405  <!--
     406  This block is translated to an HTML comment.
     407  It can contain <tags> and &entities; that will not be escaped in the output.
     408  -->
     409 
     410}}}
     411}}}
     412
     413Please note that the character sequence "--" is not allowed in HTML comments, and will generate a rendering error.
    50414
    51415
     
    57421----
    58422See also:  WikiProcessors, WikiFormatting, WikiRestructuredText
     423