ImprovedTableParser

pages/HelpOnImprovedTableParser

43:7172d229dea9
2015-02-23 Paul Boddie Updated release and copyright information.
     1 #format wiki     2 #language en     3      4 == ImprovedTableParser ==     5      6 The !ImprovedTableParser extension for !MoinMoin offers support for an alternative table syntax that is not as restrictive as the [[HelpOnTables|default syntax for tables]] in terms of the way tables are written as Wiki text, and in terms of the formatting possibilities available. For example, the default syntax insists that table rows are written on a single line - this can be challenging for rows with many columns or containing a lot of content - whereas the improved syntax allows each column to appear on one or many lines.     7      8 === The Improved Table Syntax ===     9     10 The principal syntax rules are described as follows.    11     12 ==== Making a Table ====    13     14 To make a table, make a [[HelpOnParsers|section]] and use a `#!table` declaration to indicate that it represents a table:    15     16 {{{{    17 {{{#!table    18 ...    19 }}}    20 }}}}    21     22 The result:    23     24 {{{#!table    25 ...    26 }}}    27     28 ==== Adding Rows ====    29     30 Rows are separated using the `==` marker at the start of a line. Starting a new line does not by itself start a new row:    31     32 {{{{    33 {{{#!table    34 Row #1    35 and still row #1    36 ==    37 Row #2    38 }}}    39 }}}}    40     41 The result:    42     43 {{{#!table    44 Row #1    45 and still row #1    46 ==    47 Row #2    48 }}}    49     50 ==== Adding Columns ====    51     52 Columns are separated using the `||` marker:    53     54 {{{{    55 {{{#!table    56 Column #1 || Column #2    57 }}}    58 }}}}    59     60 The result:    61     62 {{{#!table    63 Column #1 || Column #2    64 }}}    65     66 Since there is no need to indicate the start of a table or of a row, since tables are confined to sections and rows are explicitly separated, the initial and final `||` markers are not used:    67     68 {{{{    69 {{{#!table    70 Already in column #1    71 || Now in column #2    72 until the next row or the end of the table    73 }}}    74 }}}}    75     76 The result:    77     78 {{{#!table    79 Already in column #1    80 || Now in column #2    81 until the next row or the end of the table    82 }}}    83     84 ==== Indented Column Text and Line Continuation ====    85     86 Sometimes it can be convenient to present a table in a formatted fashion, with alignment of column content even when viewed as plain text. However, this can present problems with indentation:    87     88 {{{{    89 {{{#!table    90 First column || Second column    91                 ...this should be part of the same paragraph,    92                 but isn't until now.    93 }}}    94 }}}}    95     96 The result is as follows:    97     98 {{{#!table    99 First column || Second column   100                 ...this should be part of the same paragraph,   101                 but isn't until now.   102 }}}   103    104 Note how !MoinMoin lost one of the dots on the second line of the second column's text. This is a feature of the Wiki text parser.   105    106 To achieve the desired effect, a line continuation syntax is available that prevents !MoinMoin from treating the second and subsequent lines as indented paragraph text:   107    108 {{{{   109 {{{#!table   110 First column || Second column   111              .. ...this should be part of the same paragraph, and it now is,   112              .. as is this text.   113 }}}   114 }}}}   115    116 Note that the `..` marker must be the first non-space characters on a line: it is not a column separator, and does not therefore provide a way of writing column content side by side.   117    118 The result is this:   119    120 {{{#!table   121 First column || Second column   122              .. ...this should be part of the same paragraph, and it now is,   123              .. as is this text.   124 }}}   125    126 ==== Styles and Formatting ====   127    128 Style and formatting options are placed at the start of a row or column inside `<` and `>` markers, with the options corresponding to HTML attributes as described for the [[HelpOnTables|default syntax for tables]] being supported.   129    130 Table-specific options are prefixed with `table` (`tablestyle` and `tableclass` apply to the given table):   131    132 {{{{   133 {{{#!table   134 <tablestyle="width: 80%"> '''Heading'''   135 ==   136 Data   137 }}}   138 }}}}   139    140 The result:   141    142 {{{#!table   143 <tablestyle="width: 80%"> '''Heading'''   144 ==   145 Data   146 }}}   147    148 Row-specific options are prefixed with `row` (`rowstyle` and `rowclass` apply to the given row):   149    150 {{{{   151 {{{#!table   152 <rowstyle="background-color: #f99"> Red cell   153 ==   154 <rowstyle="background-color: #9f9"> Green cell   155 }}}   156 }}}}   157    158 The result:   159    160 {{{#!table   161 <rowstyle="background-color: #f99"> Red cell   162 ==   163 <rowstyle="background-color: #9f9"> Green cell   164 }}}   165    166 General options are given verbatim (`style`, `class`, `rowspan`, `colspan`).   167    168 {{{{   169 {{{#!table   170 <style="background-color: #f99"> Red cell || <rowspan=2 style="background-color: #99f"> Shared cell   171 ==   172 <style="background-color: #9f9"> Green cell   173 }}}   174 }}}}   175    176 The result:   177    178 {{{#!table   179 <style="background-color: #f99"> Red cell || <rowspan=2 style="background-color: #99f"> Shared cell   180 ==   181 <style="background-color: #9f9"> Green cell   182 }}}   183    184 Note that the short options in the default syntax are not supported. It is therefore necessary to write span and justification attributes out in full.   185    186 === A Simple Example ===   187    188 Here is a short example of a table using the features described above:   189    190 {{{{   191 {{{#!table   192 <tablestyle="width:80%" style="text-align:center" colspan=3> '''Heading'''   193 ==   194 cell 1 || cell 2 || cell 3   195 ==   196 <rowspan=2> spanning rows   197 || <colspan=2 style="background-color: #E0E0FF;"> spanning 2 columns   198 ==   199 <rowstyle="background-color: #FFFFE0;"> cell 2 || cell 3   200 }}}   201 }}}}   202    203 And here is the result:   204    205 {{{#!table   206 <tablestyle="width:80%" style="text-align:center" colspan=3> '''Heading'''   207 ==   208 cell 1 || cell 2 || cell 3   209 ==   210 <rowspan=2> spanning rows   211 || <colspan=2 style="background-color: #E0E0FF;"> spanning 2 columns   212 ==   213 <rowstyle="background-color: #FFFFE0;"> cell 2 || cell 3   214 }}}   215    216 === An Advanced Example ===   217    218 Since table cells can be described on more than one line, a wider range of Wiki syntax can be used to populate tables. For example, headings and lists can be added to tables:   219    220 {{{{   221 {{{#!table   222 == Proper Heading! ==   223 ||   224 == Another Heading! ==   225 ==   226  * First   227  * Second   228  * Third   229 ||   230  * Gold   231  * Silver   232  * Bronze   233 }}}   234 }}}}   235    236 The result:   237    238 {{{#!table   239 == Proper Heading! ==   240 ||   241 == Another Heading! ==   242 ==   243  * First   244  * Second   245  * Third   246 ||   247  * Gold   248  * Silver   249  * Bronze   250 }}}   251    252 Note that the usual restrictions around these features still apply, so headings, for example, must appear on a separate line.   253    254 === A More Advanced Example ===   255    256 Consider the following table:   257    258 ||<rowstyle="background-color: #7f7"> System || RAM || RAM<<BR>>(official expansion limit) || ROM || Year of introduction || Price on introduction (GBP) ||   259 || BBC Microcomputer Model B ||<colspan="2"> 32K || 32K || 1981 || 335 ||   260 || Acorn Electron ||<colspan="2"> 32K || 32K || 1983 || 199 ||   261 || Commodore 64 ||<colspan="2"> 64K || 20K ||<rowspan=2> 1982 || 399 ||   262 || Sinclair ZX Spectrum 48K ||<colspan="2"> 48K || 16K || 175 ||   263 || Amstrad CPC464 ||<colspan="2"> 64K || 32K || 1984 || 249 (green screen), 349 (colour) ||   264 || Amstrad CPC6128 ||<colspan="2"> 128K || 48K || 1985 || 299 (colour) ||   265 || Sinclair ZX81 || 1K || 16K || 8K || 1981 || 70 (assembled), 50 (kit) ||   266 || VIC-20 || 5K || 32K || 16K || 1980 || 200 (estimated) ||   267    268 Here is how it is written in the default table syntax:   269    270 {{{   271 ||<rowstyle="background-color: #7f7"> System || RAM || RAM<<BR>>(official expansion limit) || ROM || Year of introduction || Price on introduction (GBP) ||   272 || BBC Microcomputer Model B ||<colspan="2"> 32K || 32K || 1981 || 335 ||   273 || Acorn Electron ||<colspan="2"> 32K || 32K || 1983 || 199 ||   274 || Commodore 64 ||<colspan="2"> 64K || 20K ||<rowspan=2> 1982 || 399 ||   275 || Sinclair ZX Spectrum 48K ||<colspan="2"> 48K || 16K || 175 ||   276 || Amstrad CPC464 ||<colspan="2"> 64K || 32K || 1984 || 249 (green screen), 349 (colour) ||   277 || Amstrad CPC6128 ||<colspan="2"> 128K || 48K || 1985 || 299 (colour) ||   278 || Sinclair ZX81 || 1K || 16K || 8K || 1981 || 70 (assembled), 50 (kit) ||   279 || VIC-20 || 5K || 32K || 16K || 1980 || 200 (estimated) ||   280 }}}   281    282 Although the lines are not too long, it is somewhat difficult to interpret and edit the text.   283    284 Here is how the above table can be written in the improved syntax:   285    286 {{{{   287 {{{#!table   288 <rowstyle="background-color: #7f7"> System   289 || RAM   290 || RAM<<BR>>(official expansion limit)   291 || ROM   292 || Year of introduction   293 || Price on introduction (GBP)   294 ==   295 BBC Microcomputer Model B   296 ||<colspan="2"> 32K   297 || 32K   298 || 1981   299 || 335   300 ==   301 Acorn Electron   302 ||<colspan="2"> 32K   303 || 32K   304 || 1983   305 || 199   306 ==   307 Commodore 64   308 ||<colspan="2"> 64K   309 || 20K   310 ||<rowspan=2> 1982   311 || 399   312 ==   313 Sinclair ZX Spectrum 48K   314 ||<colspan="2"> 48K   315 || 16K   316 || 175   317 ==   318 Amstrad CPC464   319 ||<colspan="2"> 64K   320 || 32K   321 || 1984   322 || 249 (green screen), 349 (colour)   323 ==   324 Amstrad CPC6128   325 ||<colspan="2"> 128K   326 || 48K   327 || 1985   328 || 299 (colour)   329 ==   330 Sinclair ZX81 || 1K || 16K || 8K || 1981   331 || 70 (assembled), 50 (kit)   332 ==   333 VIC-20 || 5K || 32K || 16K || 1980   334 || 200 (estimated)   335 }}}   336 }}}}   337    338 Without the restriction of putting everything in a row on one line, the table can be written in a way that is as concise or as verbose as you like. Here is the result:   339    340 {{{#!table   341 <rowstyle="background-color: #7f7"> System   342 || RAM   343 || RAM<<BR>>(official expansion limit)   344 || ROM   345 || Year of introduction   346 || Price on introduction (GBP)   347 ==   348 BBC Microcomputer Model B   349 ||<colspan="2"> 32K   350 || 32K   351 || 1981   352 || 335   353 ==   354 Acorn Electron   355 ||<colspan="2"> 32K   356 || 32K   357 || 1983   358 || 199   359 ==   360 Commodore 64   361 ||<colspan="2"> 64K   362 || 20K   363 ||<rowspan=2> 1982   364 || 399   365 ==   366 Sinclair ZX Spectrum 48K   367 ||<colspan="2"> 48K   368 || 16K   369 || 175   370 ==   371 Amstrad CPC464   372 ||<colspan="2"> 64K   373 || 32K   374 || 1984   375 || 249 (green screen), 349 (colour)   376 ==   377 Amstrad CPC6128   378 ||<colspan="2"> 128K   379 || 48K   380 || 1985   381 || 299 (colour)   382 ==   383 Sinclair ZX81 || 1K || 16K || 8K || 1981   384 || 70 (assembled), 50 (kit)   385 ==   386 VIC-20 || 5K || 32K || 16K || 1980   387 || 200 (estimated)   388 }}}   389    390 === Adding Table Sorting ===   391    392 In addition to a more flexible syntax, !ImprovedTableParser also allows the contents of tables to be described so that they can be manipulated and shown according to different sorting or ordering criteria. This is done by adding some directives to the table declaration.   393    394  headers:: indicates the number of rows which are headers, describing non-sortable data   395  columntypes:: describes the kind of data in each column along with how the column data should be ordered (ascending or descending) by default if chosen as a sort column; the syntax is reminiscent of the Unix `sort` utility, but column numbering starts at 0 instead of 1   396  sortcolumns:: describes the initial sorting or ordering of the table data; the syntax is the same as `columntypes`   397  name:: the HTML `id` attribute or anchor given to the table so that when the ordering is changed, the browser will refresh the page and can jump to the table's position   398    399 To the above table, we can change the declaration as follows:   400    401 {{{{   402 {{{#!table headers=1 columntypes='2n,1nd,0,3n,4n,5n' sortcolumns='4n' name=computers   403 }}}}   404    405 This indicates that the first row is not sortable data (`headers=1`), that the column types for all but the first column (`0`) are numeric (`n`) and that the second column (`1`) should be presented in descending order by default (`d`), that the initial view will sort the data according to the fifth column (`4`) by treating its cells as if they provide numeric data. Finally, the table has an anchor called `computers` associated with it.   406    407 The result is as follows:   408    409 {{{#!table headers=1 columntypes='2n,1nd,0,3n,4n,5n' sortcolumns='4n' name=computers   410 <rowstyle="background-color: #7f7"> System   411 || RAM   412 || RAM<<BR>>(official expansion limit)   413 || ROM   414 || Year of introduction   415 || Price on introduction (GBP)   416 ==   417 BBC Microcomputer Model B   418 ||<colspan="2"> 32K   419 || 32K   420 || 1981   421 || 335   422 ==   423 Acorn Electron   424 ||<colspan="2"> 32K   425 || 32K   426 || 1983   427 || 199   428 ==   429 Commodore 64   430 ||<colspan="2"> 64K   431 || 20K   432 ||<rowspan=2> 1982   433 || 399   434 ==   435 Sinclair ZX Spectrum 48K   436 ||<colspan="2"> 48K   437 || 16K   438 || 175   439 ==   440 Amstrad CPC464   441 ||<colspan="2"> 64K   442 || 32K   443 || 1984   444 || 249 (green screen), 349 (colour)   445 ==   446 Amstrad CPC6128   447 ||<colspan="2"> 128K   448 || 48K   449 || 1985   450 || 299 (colour)   451 ==   452 Sinclair ZX81 || 1K || 16K || 8K || 1981   453 || 70 (assembled), 50 (kit)   454 ==   455 VIC-20 || 5K || 32K || 16K || 1980   456 || 200 (estimated)   457 }}}   458    459 By pointing to the header cells, a pop-up dialogue allows the sorting criteria to be edited.   460    461  * Where a column is already being used to sort the data, it will appear in the list of sort columns.   462  * By opening the dialogue over a sort column, the column can be removed from the criteria by selecting it in the list. (It will appear crossed out when pointed to.)   463  * A column can be moved or inserted into the criteria by pointing to another column or the space at the end of the list. The column should appear at its new position and can be inserted by selecting the region next to which (or within which) the new column appears, or by selecting the arrows in the new column indicator.   464  * The sort direction for a column can be changed by selecting the highlighted arrow next to its name.