niceTables.pl

Jump to: Site Navigation

niceTables.pl

Subroutines for creating tables that * conform to accessibility standards * allow a lot of CSS flexibility for on-screen styling * allow some LaTeX flexibility for hard copy styling

Hard copy data tables will always have a top rule, bottom rule, and midrule after any header row

DataTable() Creates a table with data. Should not be used for layout, such as displaying an array of graphs. Should usually make use of a caption and column and/or row headers.

LayoutTable() Creates a "table" using div boxes for layout

NOTE: In order to reduce separate setting of on-screen and hard copy settings as much as possible, Perl 5.10+ tools are used. These macros may behave unexpectedly or not work at all with older versions of Perl. These macros use LaTeX packages in the hard copy that wer not formerly part of a WeBWorK hard copy preamble. Your LaTeX distribution needs to have the packages: booktabs, tabularx, colortbl, caption, xcolor And if you have a WeBWorK version earlier than 2.10, you need to add calls to these packages to hardcopyPreamble.tex in webwork2/conf/snippets/

Description

Command for tables displaying data. In a data table the xy-position of a cell is somehow important along with the information inside the cell.

        Usage:  DataTable([[a,b,c,...],[d,e,f,...],[g,h,i,...],...], options);

        [[a,b,c,...],[d,e,f,...],[g,h,i,...],...] is the table content, row by row

As much as possible, options can be declared to simultaneously apply to both on-screen and hard copy. Generally, you give settings for the hard copy tex version first. Many common such settings are automatically translated into CSS styling for the on-screen. You can then override or augment the CSS for the on-screen version.

With PTX output, not all features below are supported. Perhaps they can be added upon request. Contact Alex Jordan with questions. This version supports the center, caption, midrules, encase, and noencase options in PTX. It also honors the horizontal alignment portions of the align option (but not vertical rules or anything found in @{}).

Options for the WHOLE TABLE

    Applies to on-screen *and* hard copy:
      center => 0 or 1              # center table
      caption => string             # a caption for the table
      midrules => 0 or 1            # if you want rules above and below every row
                                    #   (hard copies will always have toprule and bottomrule)
      align => string               # an alignment string like the kinds used in LaTeX tabular environments;
                                    # some of what you specify here will apply to both on-screen and hard copy
        (texalignment => string     #  -what won't is specified further below
         is really what it is,      # for example 'rccp{1in}' would be for a four-column table with a
         but align is a shortcut)   #   right-aligned column, two centered columns,
                                    #   and a paragraph column of fixed width 1in; defaults to all c's;
                                    # r is for right-alignment; on-screen will have no wrap
                                    # c for center; on-screen will have no wrap
                                    # l for left; on-screen will have no wrap
                                    # p{width} is for a fixed-width paragraph column
                                    #   -width should be a valid tex width; if it is also a valid css width,
                                    #   -it will be used on-screen too; otherwise, on-screen will have unspecified width
      Xratio => 0.97                # X ...if X is used in column alignment then the hard copy will have a width that
                                    #   is Xratio times the \linewidth, and X columns will be paragraph columns that
                                    #   grow to be whatever width fills the overall table width. For on-screen, X is
                                    #   a normal breaking-paragraph column that will expand to screen width before
                                    #   a break happens
                                    # | as with array environments in LaTeX, you may use | for vertical rules.
                                    # Preceding one of the above alignment types, you may use >{...} where the ... is
                                    #   more LaTeX commands to be applied everywhere in the column. For the simple text
                                    #   syling commands: \bfseries for bold, \itshape for italic, or \ttfamily for
                                    #   teletype (monospaced font), the on-screen version will be applied too.
                                    #  *You may include \color{...} here too, where ... is a coloring mixture from the
                                    #   xcolor package. 'blue' is an example of the simplest coloring mixture. For a much
                                    #   more complicated example: rgb:blue!30!green,1;-red!10!green,2 would give 1 part
                                    #   a 30%blue-70%green mixture, mixed with 2 parts the complement of a
                                    #   10%red-90%green mixture.
                                    #     -only mixtures like \color{blue...} will be respected on-screen, and in that
                                    #     -case the first color will named be used. Use columnscss (discussed below) if
                                    #     -want to be more picky with the on-screen version.
                                    #  *You may include \columncolor{...} to color the background of cells, where ...
                                    #   follows the same rules as for \color{...}
                                    #  NOTE: Any color commands (\color, \columncolor, \rowcolor, \cellcolor) can take the
                                    #    option [HTML] and then an HTML hexadecimal color can be declared. For example,
                                    #    \color[HTML]{FF0000} for red. It works for on-screen and hard copy. Color
                                    #    specified this way should be the same on-screen and in the hard copy, whereas
                                    #    color specified the other way often differs.
                                    #   Any more complicated tex commands will be ignored for on-screen (or cause errors
                                    #     or not behave as expected).
      encase => array ref           # You may want to encase all table entries in, say, \( and \) to save from typing
                                    #   them many times. To do that, use encase => ['\(','\)']. For individual cells
                                    #   you may set noencase=>1 to omit this (see section on modifying cells).
      rowheaders => 1               # Make the first element of every row a row header.

    Applies to on-screen:
      tablecss => string            # css styling commands for the table element (see below for css syntax)
      captioncss => string          # css styling commands for the caption element (see below for css syntax)
      columnscss => array ref       # an array reference to css styling commands (strings) for columns
                                    #   use empty strings for columns for which you have no style specifications
                                    #   Ex: columnscss => ['','background-color:yellow;','','background-color:yellow;']
                                    #   -specifications made here overrule specifications from texalignment
      datacss => string             # css styling commands for all the td elements (see below for css syntax)
      headercss => string           # css styling commands for the th elements (see below for css syntax)
      allcellcss => string          # css styling commands for all the cells (see below for css syntax)

MODIFYING CELLS

  Each cell entry (like "a" in [[a,b,c,...],...])) can be replaced with an array reference (encased in square brackets) for
  more detailed customization of that cell. For example, [[[a,header=>'CH'],b,c],[d,e,f]] gives a table where the a is
  a column header cell. The data content of the cell must be the first element listed, and what follows must be key=>value pairs.
  These options may be applied.

    Applies to both on-screen and hard copy:
      halign => string              # same format as align at the table level (discussed above) but for one cell only
      header => type,               # Could be 'TH' (table header), 'CH', 'col', or 'column' (col header), 'RH', or 'row'
                                    #   (row header). If so, default CSS styling is used, and hard copy cell is bold.
                                    # Can also be 'TD' to overrule a row of all headers (see modifying rows)
                                    # If your table only has column headers (no row headers) it is probably best to make
                                    #   an entire row of headers (see modifying a row) and to not use header=> directly.
                                    #   But if your table has both column and row headers then use header=> for all the
                                    #   headers (both row- and column-) and don't use the row modification (because in
                                    #   that situation you probably don't want a THEAD tag).
      tex => tex code               # For tex commands whose scope will be entire cell, e.g. \bfseries or \itshape;
                                    #   \bfseries (for bold), \itshape (for italic), and \ttfamily (for monospace) will
                                    #   lead to CSS equivalents for the on-screen version
                                    # For cell coloring: like \cellcolor{blue} for the background or \color{blue} for the
                                    #   text, use color mixtures as described in texalignment=>, and simple colors will
                                    #   apply to the on-screen version too.
                                    # -all other tex code will be ignored for the on-screen version, so use cellcss=>
                                    #  below
      b=>1, i=>1, m=>1              # These are shortcuts for adding \bfseries, \itshape, and \ttfamily to tex, which will
                                    #   in turn affect he on-screen too.
      noencase => 1                 # If you have global encase strings (see section on modifying the whole table) then
                                    #   you can opt to not apply them on a cell by cell basis
      colspan => pos integer        # for cells that span more than one column; when using this, you must set halign for
                                    #   the cell too, or else the tex output will just use {c} alignment; this feature may
                                    #   not behave as expected for certain structures, like a two-row table, with 3 columns,
                                    #   but the first row has colspans 2 and 1 with the second row having colspans 1 and 2
                                    # **colspan is supported for DataTable only, not LayoutTable. LayoutTable uses css
                                    #   like display:table-cell; to achieve its output, and there is no counterpart to
                                    #   colspan using this approach (at least not currently)

    Applies to on-screen:
      cellcss => string,            # String with cell-specific CSS styling; see below for CSS syntax

    Applies to hard copy:
      texpre => tex code,           # For more fussy cell-by-cell alteration of the tex version of the table
                                    # TeX code here will precede the cell entry...
      texpost => tex code           # and code here will follow the cell entry
                                    # The ordering will be: texpre tex data texpost
      texencase => array ref        # This is just a shortcut for entering [texpre,texpost] at once.

  The "a" in a cell can also be replaced directly with a hash reference {data=>a,options} if somehow that is of use. If you
  modify the cell using an array reference [a, options] instead, it is automatically converted to a hash reference anyway.

MODIFYING ROWS

 You can give a row background color using arguments from colortbl's \rowcolor command:
    [[[a, rowcolor => '{blue!50}'],b,c,...],[d,e,f,...],[g,h,i,...],...]
    [[[a, rowcolor => '[HTML]{FF0000}'],b,c,...],[d,e,f,...],[g,h,i,...],...]
 For the on-screen version, if the first style of argument is used, only the first color mentioned will be used.

 A rowcss key can be used anywhere in the row. Only the last instance in that row will be applied.
    [[[a, rowcss => extra css for the row],b,c,...],[d,e,f,...],[g,h,i,...],...]

 You can make an entire row be made of CH (column header) elements without specifying it for each header:
    [[[a, headerrow=>1],b,c,...],[d,e,f,...],[g,h,i,...],...]
 This also encases the row in a <THEAD> tag. This should only be applied to the first row. In the hard copy,
    a row like this will have bold entries and be followed by a midrule.

 And you can follow a row with a horizontal rule:
    [[[a, midrule => 1],b,c,...],[d,e,f,...],[g,h,i,...],...]
    (but this is already done once for headerrows in the hard copy, since they don't rely on surrounding CSS to stand out)

CSS SYNTAX PRIMER

      css styling commands offer a huge variety for styling the table on screen
      Basic elements are of the form "A:B;" like "border:1pt;" and "width:80%;"
      ****DON'T FORGET THE SEMICOLONS. SINCE THESE COMMANDS ACCUMULATE, SEMICOLONS ARE IMPORTANT.
      Also, they can be of the form "A:B C;" like "border:1pt dashed;"
      Multiple commands can be used with the form "A1:B;A2:C;" like "border:1pt; margin:5pt;"
      Some properties with example values and which elements they can affect:
          border:2px solid blue;                      table, caption, th, td
          border-collapse:collapse;  (or separate)    table
          border-radius: 5px;                         table, caption, tr, th, td
          width:50%;                                  table, caption, th, td
          height:20ex;                                table, caption, tr, th, td
          text-align:center;                          table, caption, tr, th, td
          vertical-align:top;                         table, caption, tr, th, td
          padding:12pt;                               table, caption, th, td
          margin:20px;                                table, caption
          border-spacing:12pt;                        table
          caption-side:bottom;                        table, caption
          color:blue;                                 table, caption, tr, th, td
          background-color:yellow;                    table, caption, tr, th, td
          font-weight:bold;                           table, caption, tr, th, td
          font-style:italic;                          table, caption, tr, th, td
          font-family:monospace;                      table, caption, tr, th, td
      The properties border, padding, and margin
          can be specified in more detail using -left, -bottom, -right, -top as in "border-bottom:5px"

        Example: DataTable([[[1, header => 'CH', cellcss => 'font-family:fantasy;'],2,3],
                    [4,5,[6, rowcss => 'padding-top:10pt; padding-bottom:10pt; ']]],
                     tablecss => "border:solid 1px; border-spacing:5px; border-radius: 5px; border-collapse:separate;");

Command for table to control layout

Usage: LayoutTable(...) See usage for DataTable. The HTML output will use section and div boxes instead of HTML tabling elements Anything having to do with headers, captions, and data cells no longer make sense (although 'data' is still used as the key for cell contents).


Site Navigation