hygguile_components_table (Untitled Document)

1.22 (hygguile components table)

Procedures

1.22.1 Procedures

Procedure: caption content KEY: #:position #:classes ¶

Create an HTML <caption> naming a data table.

A caption is the accessible name of the table: assistive technology announces it when the table is reached, so it is worth writing even when a nearby heading says almost the same thing.

content: The caption text string or inline nodes.
position: A symbol placing the caption above ('top, the default) or below ('bottom) the table, purely through the caption-side property.
classes: List of symbols representing typography CSS classes.

(caption "Quarterly revenue")

Procedure: parse-sort params KEY: #:columns #:default-direction ¶

Read the requested sort state out of a decoded query.

This is the other half of sortable-table: the component writes the order into the URL, and this reads it back on the following request, so a route only has to hand over the query it decoded. Only the two prefixed names are read, so a sort or a dir belonging to the page’s own query is left to the page.

A key no column declares is reported as no sort at all rather than passed through, so a hand-edited, stale or truncated link falls back to the natural order instead of reaching the query layer. The key that comes back is the column’s own, not the string from the URL, so it can be compared with eq? and handed straight back to sortable-table.

params: The decoded query, an association list such as '(("hygguile-table-sort" . "seats")); symbol names and (name value) pairs are accepted too.
columns: The column descriptors given to sortable-table, or a plain list of sort keys.
default-direction: The direction used when the URL asks for none. Defaults to 'asc.

Returns a two-element list, (key direction), where key is #f when the request asks for the natural order.

(parse-sort '(("hygguile-table-sort" . "seats")
              ("hygguile-table-dir" . "desc"))
            #:columns (list (table-column #:key 'seats #:label "Seats")))
;; => (seats desc)

Procedure: sort-href KEY: #:path #:params #:drop-params #:sort #:direction ¶

Build the URL asking the server to order a table by sort in direction.

The link a header cell carries is the whole sorting state: the server reads it back on the next request, and a reload or a shared link reproduces the same order without any scripting. The order itself travels in hygguile-table-sort and hygguile-table-dir, prefixed so that a page’s own sort or dir parameter is never mistaken for the table’s state. Every value is URL-encoded, and the parameters named in drop-params are left out, because they describe a position in the order that is being replaced: keeping page=4 while the sort changes would show an arbitrary slice of the new order. Sorting therefore starts at the first page.

An order already present in params is replaced, not repeated, so the whole query such a page received can be handed straight back in without the link contradicting itself. Parameters of the page’s own are carried over untouched, however they are named: a page whose sort means something else keeps it.

With no path the href is a bare query, such as ?hygguile-table-sort=seats&hygguile-table-dir=desc, which the browser resolves against the page’s own path. That is what a table route wants, since one route renders the page and handles the sort.

path: An optional path to prefix the query with, such as "/plans".
params: An association list of other query parameters to carry over, such as '(("filter" . "active")). Symbol names and non-string values are converted.
drop-params: Names removed from params first. Defaults to "page".
sort: The key of the column to order by, as a symbol or a string. #f asks for the natural order instead, which is how a "stop sorting" link is built.
direction: 'asc (the default) or 'desc.

(sort-href #:params '(("page" . "4"))
           #:sort 'seats #:direction 'desc)
;; => "?hygguile-table-sort=seats&hygguile-table-dir=desc"

Procedure: sortable-table KEY: #:columns #:rows #:sort #:direction #:path #:params #:drop-params #:default-direction #:caption #:caption-position #:caption-classes #:scroll #:scroll-label #:table-classes #:container-classes #:head-classes #:header-classes #:cell-classes #:row-classes #:empty-message #:empty #:sticky-header? #:selectable? #:select-name #:row-keys #:resizable? #:density #:zebra? #:loading? #:loading-rows #:error #:retry ¶

Create a data table whose column order lives in the URL.

Each sortable header cell is a link to the same page carrying hygguile-table-sort and hygguile-table-dir, and the cell announces the state it is in through aria-sort. Nothing runs in the browser: clicking a header is an ordinary navigation, so the table sorts with JavaScript disabled, a reload reproduces the order, and a shared link opens on the same view. The server reads the order back with parse-sort.

Clicking the column the table is already ordered by reverses it; clicking another starts that column in its own direction. The other query parameters travel along, except those in drop-params, so a filter survives a sort while a page number does not.

columns: A list of table-column descriptors, or of bare sort keys.
rows: A list of rows, each a list of cell contents matching the columns by position. A short row simply leaves its trailing cells empty.
sort: The key of the column currently ordered, or #f for the natural order. A key no column declares is ignored.
direction: The current direction, 'asc (the default) or 'desc.
path: The path the links point at, when it differs from the page that renders them. By default they are bare queries, which keep the current path.
params: Other query parameters to carry over, as for sort-href.
drop-params: Parameters removed when the sort changes. Defaults to "page".
default-direction: The direction a column starts in when it declares none.
caption: An optional caption rendered as the table’s own caption element.
caption-position: A symbol placing that caption 'top (default) or 'bottom.
caption-classes: List of symbols representing caption typography CSS classes.
scroll: A boolean wrapping the table in an accessible horizontally scrollable region.
scroll-label: An optional accessible name for that region; it defaults to a string caption.
table-classes: List of symbols representing the table layout CSS classes.
container-classes: List of symbols representing the scroll container CSS classes.
head-classes: List of symbols representing the header row group CSS classes.
header-classes: List of symbols representing a sortable header cell. The cell’s padding moves to the link, so the link covers the whole cell.
cell-classes: List of symbols representing the data cell CSS classes.
row-classes: List of symbols representing each body row’s CSS classes.
empty-message: What a table with no rows says, spanning every column.

A totals row or any other bespoke footer is the one thing this component leaves out: reach for table with tfoot, and for sort-href plus th #:aria-sort to build the header the same way by hand.

(sortable-table #:columns (list (table-column #:key 'plan #:label "Plan")
                                (table-column #:key 'seats #:label "Seats"
                                              #:numeric #t))
                #:rows (list (list "Cozy" "3"))
                #:sort 'seats #:direction 'desc
                #:caption "Plans")

Procedure: table content KEY: #:caption #:caption-position #:caption-classes #:scroll #:scroll-label #:table-attributes #:container-attributes #:table-classes #:container-classes ¶

Create a semantic HTML <table> for tabular data.

Rows are built from thead, tbody, tfoot, tr, th and td nodes, so every piece of the table keeps its native meaning: browsers, screen readers and crawlers all understand the relationship between headers and cells without any scripting.

Wide tables are a common source of horizontal page overflow on phones. By default the table is therefore wrapped in a scrollable region that carries role="region" and an accessible name, and that is reachable with tabindex, so keyboard users can scroll it too. Pass #:scroll #f when you would rather handle the overflow yourself.

content: The row groups making up the table, typically a thead, a tbody and an optional tfoot.
caption: An optional caption rendered as the table’s own caption element.
caption-position: A symbol placing that caption 'top (default) or 'bottom.
caption-classes: List of symbols representing caption typography CSS classes.
scroll: A boolean wrapping the table in an accessible horizontally scrollable region.
scroll-label: An optional accessible name for that region; it defaults to a string caption.
table-attributes: Extra attributes for the <table> itself, as pairs.
container-attributes: Extra attributes for the scroll region, as pairs.
table-classes: List of symbols representing the table layout CSS classes.
container-classes: List of symbols representing the scroll container CSS classes.

(table (list (thead (list (tr (list (th "Plan" #:scope 'col)
                                   (th "Price" #:scope 'col #:numeric #t)))))
             (tbody (list (tr (list (td "Cozy")
                                    (td "9" #:numeric #t))))))
       #:caption "Plans")

Procedure: table-column KEY: #:label #:key #:numeric #:sortable #:default-direction #:align #:nowrap ¶

Describe one column of a sortable-table.

label: The text shown in the header cell. When omitted, the sort key is used.
key: The sort key this column is ordered by, and the value that travels in the URL as ?hygguile-table-sort=. Symbols are conventional. A column without a key is rendered but not sortable, which is what a column of row actions wants.
numeric: A boolean right-aligning the column and letting its digits line up.
sortable: A boolean; #f renders a plain header cell even when a key is given.
default-direction: The direction the first click on this column asks for, 'asc or 'desc. Defaults to the table’s own #:default-direction.
align: A symbol, one of 'left, 'right or 'center, overriding the numeric default.
nowrap: A boolean preventing this column’s cells from wrapping.

(table-column #:key 'seats #:label "Seats" #:numeric #t)

Procedure: tbody rows KEY: #:classes ¶

Create an HTML <tbody> row group holding the data rows.

rows: A list of tr rows built from td cells.
classes: List of symbols representing the body group CSS classes.

(tbody (list (tr (list (td "Ada Lovelace")))))

Procedure: td content KEY: #:align #:numeric #:nowrap #:colspan #:classes ¶

Create an HTML <td> data cell.

content: The cell text string or inline nodes.
align: A symbol, one of 'left, 'right or 'center. By default a cell inherits the table’s alignment.
numeric: A boolean enabling tabular figures and, unless align says otherwise, right-aligning the cell, so columns of numbers line up digit by digit.
nowrap: A boolean preventing the cell from wrapping.
colspan: A number of columns this cell spans, which is what a totals row and an empty state need.
classes: List of symbols representing the data cell CSS classes.

(td "1 204" #:numeric #t)

Procedure: tfoot rows KEY: #:classes ¶

Create an HTML <tfoot> row group for summaries and totals.

rows: A list of tr rows, usually a single row of totals.
classes: List of symbols representing the footer group CSS classes.

(tfoot (list (tr (list (th "Total" #:scope 'row)
                       (td "42" #:numeric #t)))))

Procedure: th content KEY: #:scope #:align #:numeric #:nowrap #:colspan #:aria-sort #:resizable? #:classes ¶

Create an HTML <th> header cell.

Every header is given an explicit scope by default, which lets assistive technology tie the header to the column or row it describes without guessing.

content: The header text string or inline nodes.
scope: A symbol, one of 'col (default), 'row, 'colgroup or 'rowgroup.
align: A symbol, one of 'left, 'right or 'center. By default a header inherits the table’s alignment.
numeric: A boolean enabling tabular figures and, unless align says otherwise, right-aligning the header.
nowrap: A boolean preventing the header from wrapping.
colspan: A number of columns this cell spans.
aria-sort: A symbol or string from ascending, descending or none. Set by sortable-table to announce the order a sortable column is in; none marks a column that can be sorted but is not.
resizable?: Whether the header cell carries a column-resize handle (an enhancement).
classes: List of symbols representing the header cell CSS classes.

(th "Price" #:align 'right #:numeric #t)

Procedure: thead rows KEY: #:classes ¶

Create an HTML <thead> row group holding the column headers.

rows: A list of tr rows built from th cells.
classes: List of symbols representing the header group CSS classes.

(thead (list (tr (list (th "Name" #:scope 'col)))))

Procedure: tr cells KEY: #:classes ¶

Create an HTML table row (<tr>) from a list of cells.

cells: A list of th or td cells.
classes: List of symbols representing optional row CSS classes.

(tr (list (td "Cozy") (td "9" #:numeric #t)))