diff options
Diffstat (limited to 'content/articles')
| -rw-r--r-- | content/articles/table-shortcode-examples.md | 1375 |
1 files changed, 1375 insertions, 0 deletions
diff --git a/content/articles/table-shortcode-examples.md b/content/articles/table-shortcode-examples.md new file mode 100644 index 0000000..093ef1c --- /dev/null +++ b/content/articles/table-shortcode-examples.md @@ -0,0 +1,1375 @@ +--- +slug: "table-shortcode-examples" +title: "Table Shortcode Examples" + +# date (optional for articles) +date: "2021-10-22T23:11:04-04:00" + +# show on articles page +# show: true + +# uncomment to show table of contents +toc: true + +# custom table config for all tables on this page +table_config: + table_class: "table" + align_left: "has-text-left" + align_center: "has-text-centered" + align_justify: "has-text-weight-bold" + align_right: "has-text-right" + +tables: + # available table properties + table_props: + name: "Table Properties" + + cols: + - id: "id" + name: "Property" + tip: "Property ID." + - id: "required" + name: "Required?" + tip: "Is this property required?" + - id: "text" + name: "Description" + tip: "Property description." + - id: "notes" + name: "Notes" + tip: "Property notes." + + rows: + - id: "`id`" + required: "No" + text: "Table ID." + notes: "Used as the `id` attribute of the `<table>` element." + - id: "`css`" + required: "No" + text: "Table [CSS](https://en.wikipedia.org/wiki/CSS) class." + notes: "Appended to the `class` attribute of the `<table>` element." + - id: "`name`" + required: "No" + text: "Table name." + notes: "Used as the value of the `title` attribute and `aria-label` attribute of the `<table>` element if the `tip` property is not specified." + - id: "`tip`" + required: "No" + text: "Table tooltip." + notes: "Used as the value of the `title` attribute and `aria-label` attribute of the `<table>`." + - id: "`config`" + required: "No" + text: "Table config." + notes: "Used to override the configuration for this table." + - id: "`caption`" + required: "No" + text: "Table caption." + notes: "Value of `<caption>` element for this table." + - id: "`cols`" + required: "**Yes**" + text: "Table columns." + notes: "Array of column definitions." + - id: "`rows`" + required: "**Yes**" + text: "Table rows." + notes: "Array of rows." + + # available column properties + col_props: + name: "Column Properties" + + cols: + - id: "id" + name: "Property" + tip: "Property ID." + - id: "required" + name: "Required?" + tip: "Is this property required?" + - id: "text" + name: "Description" + tip: "Property description." + - id: "notes" + name: "Notes" + tip: "Property notes." + + rows: + - id: "`id`" + required: "**Yes**" + text: "Row property which contains the cell value." + notes: "n/a" + - id: "`name`" + required: "**Yes**" + text: "Column name." + notes: "Used as the content of `<th>` elements and as the tooltip for `<th>` and `<td>` elements if the `tip` column property is not defined." + - id: "`tip`" + required: "No" + text: "Column tooltip." + notes: "Used for the `title` and `aria-lable` attributes of `<th>` and `<td>` elements." + - id: "`align`" + required: "No" + text: "Column alignment." + notes: "One of `left`, `center`, `justify`, or `right`." + + # available row properties + row_props: + name: "Row Properties" + + cols: + - id: "id" + name: "Property" + tip: "Property ID." + - id: "required" + name: "Required?" + tip: "Is this property required?" + - id: "text" + name: "Description" + tip: "Property description." + - id: "notes" + name: "Notes" + tip: "Property notes." + + rows: + - id: "`_id`" + required: "No" + text: "Row ID." + notes: "Used as the `id` attribute of the generated `<tr>` element." + - id: "`_css`" + required: "No" + text: "Row [CSS class](https://en.wikipedia.org/wiki/CSS)." + notes: "Used as value of the `class` attribute of the generated `<tr>` element." + - id: "`_tip`" + required: "No" + text: "Row tooltip." + notes: "Used as value of the `title` attribute and the `aria-label` attribute of the generated `<tr>` element." + + row_attrs: + name: "Row Attributes" + + cols: + - id: "id" + name: "Attribute" + tip: "Attribute name." + - id: "text" + name: "Description" + tip: "Attribute description." + - id: "notes" + name: "Notes" + tip: "Attribute notes." + + rows: + - id: "`id`" + text: "n/a" + notes: "Generated if the `_id` row property is specified." + - id: "`title`" + text: "Row tooltip." + notes: "Generated if the `_tip` row property is specified." + - id: "`aria-label`" + text: "Row tooltip." + notes: "Generated if the `_tip` row property is specified." + - id: "`class`" + text: "Row tooltip." + notes: "Generated if the `_css` row property is specified." + - id: "`data-tr_y`" + text: "Zero-indexed Y offset of row position in table." + notes: "Can be used to match specific rows using [CSS](https://en.wikipedia.org/wiki/CSS) selectors. Example `#some-table tr[data-tr_y='2']`." + + # available cell properties + cell_props: + name: "Cell Properties" + + cols: + - id: "id" + name: "Property" + tip: "Property ID." + - id: "required" + name: "Required?" + tip: "Is this property required?" + - id: "text" + name: "Description" + tip: "Property description." + - id: "notes" + name: "Notes" + tip: "Property notes." + + rows: + - id: "`id`" + required: "No" + text: "Cell ID." + notes: "Used as the `id` attribute of the generated `<td>` element." + - id: "`tip`" + required: "No" + text: "Cell tooltip." + notes: "Used as value of the `title` attribute and the `aria-label` attribute of the generated `<td>` element." + - id: "`align`" + required: "No" + text: "Cell alignment." + notes: "One of `left`, `center`, `justify`, or `right`." + - id: "`html`" + required: "No" + text: "Render cell value as HTML?" + notes: "One of `true` or `false`. Defaults to `false`." + - id: "`css`" + required: "No" + text: "Cell [CSS class](https://en.wikipedia.org/wiki/CSS \"Cascading Style Sheets\")." + notes: "Overrides the `align` property if specified." + - id: "`val`" + required: "No" + text: "Cell value." + notes: "Rendered as [HTML](https://en.wikipedia.org/wiki/HTML \"HyperText Markup Language\") if the `html` property is true, and [Markdown](https://en.wikipedia.org/wiki/Markdown \"Markdown markup language\") otherwise." + + cell_attrs: + name: "Cell Attributes" + + cols: + - id: "id" + name: "Attribute" + tip: "Attribute name." + - id: "text" + name: "Description" + tip: "Attribute description." + - id: "notes" + name: "Notes" + tip: "Attribute notes." + + rows: + - id: "`id`" + text: "n/a" + notes: "Generated if the `id` cell property is specified." + - id: "`title`" + text: "Row tooltip." + notes: "Set to the value of `tip` cell property is specified, or followed by the value of the `tip` column property. Defaults to the name of the column otherwise." + - id: "`aria-label`" + text: "Row tooltip." + notes: "Set to the value of `tip` cell property is specified, or followed by the value of the `tip` column property. Defaults to the name of the column otherwise." + - id: "`class`" + text: "Cell [CSS class](https://en.wikipedia.org/wiki/CSS)." + notes: "Generated if the `css` cell property is specified, if + the cell `align` property is specified, or if the column `align` property is specified." + - id: "`data-td_x`" + text: "Zero-indexed X offset of cell position in table." + notes: "Can be used to match specific columns using [CSS](https://en.wikipedia.org/wiki/CSS) selectors. Example `#some-table td[data-td_x='3']`." + - id: "`data-td_id`" + text: "Cell column ID." + notes: "Can be used to match specific columns using [CSS](https://en.wikipedia.org/wiki/CSS) selectors. Example `#some-table td[data-td_id='text']`." + + # available column alignments + align_classes: + cols: + - id: "align" + name: "align" + tip: "Value of column `align` property." + - id: "class" + name: "class" + tip: "Generated class attribute for <th> and <td> elements." + + rows: + - align: "`left`" + class: "`has-text-left`" + - align: "`center`" + class: "`has-text-centered`" + - align: "`justify`" + class: "`has-text-justified`" + - align: "`right`" + class: "`has-text-right`" + + # available table configuration properties + table_config_props: + cols: + - id: "id" + name: "Property ID" + tip: "Property ID." + - id: "text" + name: "Description" + tip: "Property description." + - id: "notes" + name: "Notes" + tip: "Property notes." + - id: "default" + name: "Default Value" + tip: "Default value." + + rows: + - id: "`data_prefix`" + text: "Prefix used for all `data-` attributes." + notes: "Used to prevent data attribute clashes. For example, if `data_prefix` is set to `zz_`, then the `data-td_x` attribute will be generated as `data-zz_td_z`." + default: "(empty)" + - id: "`table_class`" + text: "Base table [CSS](https://en.wikipedia.org/wiki/CSS \"Cascading Style Sheets\") class." + notes: "The `css` property of tables is appended to this class to form the class list. For example, if a table has a `css` property of of `foobar`, then the `<table>` element will be generated with a `class` attribute of `class='table foobar'`." + default: "`table`" + - id: "`align_left`" + text: "Class for left-aligned `<th>` and `<td>` elements." + notes: "n/a" + default: "`has-text-left`" + - id: "`align_center`" + text: "Class for center-aligned `<th>` and `<td>` elements." + notes: "n/a" + default: "`has-text-centered`" + - id: "`align_justify`" + text: "Class for justified `<th>` and `<td>` elements." + notes: "n/a" + default: "`has-text-justified`" + - id: "`align_right`" + text: "Class for right-aligned `<th>` and `<td>` elements." + notes: "n/a" + default: "`has-text-right`" + + # example of simple array table + fruits: + - ["name", "text"] + - ["apple", "red"] + - ["banana", "yellow"] + - ["grape", "green"] + + # example of columns defined as arrays + cols_as_array: + cols: ["name", "text"] + rows: + - ["apple", "red"] + - ["banana", "yellow"] + - ["grape", "green"] + + # example of columns and rows defined as hashes + hashes: + cols: + - id: "name" + name: "Name" + - id: "text" + name: "Text" + + rows: + - name: "apple" + text: "red" + - name: "banana" + text: "yellow" + - name: "grape" + text: "green" + + # example of table with caption + table_caption: + caption: "an example caption" + cols: ["name", "text"] + rows: + - ["apple", "red"] + - ["banana", "yellow"] + - ["grape", "green"] + + # example of column tooltips + column_tooltips: + cols: + - id: "name" + name: "Name" + tip: "The name of the fruit." + - id: "text" + name: "Text" + tip: "A brief description of the fruit." + + rows: + - name: "apple" + text: "red" + - name: "banana" + text: "yellow" + - name: "grape" + text: "green" + + # example of column alignment + column_alignment: + cols: + - id: "name" + name: "Name" + align: "left" + - id: "text" + name: "Text" + align: "right" + + rows: + - name: "apple" + text: "red" + - name: "banana" + text: "yellow" + - name: "grape" + text: "green" + + # example of table with cells as values + cells_as_values: + cols: + - id: "name" + name: "Name" + - id: "text" + name: "Text" + + rows: + - name: "apple" + text: "red" + - name: "banana" + text: "yellow" + - name: "grape" + text: "green" + + # example of table a single cell defined cells as a hash + cells_as_hashes: + cols: + - id: "name" + name: "Name" + - id: "text" + name: "Text" + align: "right" + + rows: + - name: "apple" + text: "red" + - name: "banana" + text: "yellow" + - name: "grape" + text: + # cell with custom alignment and tooltip + val: "green" + align: "left" + tip: "This cell has a custom tooltip." + + # example of table with cells using markdown markup + cell_markup_markdown: + cols: + - id: "name" + name: "Name" + - id: "text" + name: "Text" + + rows: + - name: "apple" + text: "*red*" # italics + - name: "banana" + text: "**yellow**" # bold + - name: "grape" + text: "[green](https://pablotron.org/ \"my favorite site\")" # link + + # example of table with cells using html markup + cell_markup_html: + cols: + - id: "name" + name: "Name" + - id: "text" + name: "Text" + + rows: + - name: "apple" + # cell value using HTML markup for italics + text: + val: "<i>red</i>" + html: true + - name: "banana" + # cell value using HTML markup for bold + text: + val: "<b>yellow</b>" # bold + html: true + - name: "grape" + # cell value using HTML markup for a link + text: + val: "<a href='https://pablotron.org/' title='my favorite site'>green</a>" + html: true + + table_with_config_override: + # table config override that renders right-aligned text as bold + config: + table_class: "table" + align_left: "has-text-left" + align_center: "has-text-centered" + align_justify: "has-text-justified" + align_right: "has-text-weight-bold" + + cols: + - id: "name" + name: "Name" + - id: "text" + name: "Text" + align: "right" + + rows: + - name: "apple" + text: "red" + - name: "banana" + text: "yellow" + - name: "grape" + text: "green" + +--- + +## Introduction + +This shortcode is a replacement for the lackluster table syntax in the +default [Hugo Markdown renderer][goldmark]. + +Features: +* Emits [CSS][] classes for alignment rather than inline `style` + attributes (no more `unsafe-inline`). +* Table can be defined as [front matter][front matter] or [site data][]. +* Column tooltips. +* Cell-specific overrides (alignment, tooltip, etc). +* [HTML][] and [Markdown][] markup support. +* Easy to configure emitted [CSS][] classes for a variety of frameworks, + including [Bulma][] and [Bootstrap][]. + +## Quick Start + +To get started: + +1. Copy `table.html` from the [hugo-shortcode-table + repository][hugo-shortcode-table] to the `layouts/shortcodes` + directory for your site. +2. Add a table definition to your [page front matter][front matter] (see + below). +3. Add a `table` shortcode to your page content which references the + table definition from the previous step (see below). + +Here is an example table definition for [YAML][] [front matter][]: + +```yaml +tables: + fruits: + - ["name", "text"] + - ["apple", "red"] + - ["banana", "yellow"] + - ["grape", "green"] +``` + + +Here is an example table declaration for your page content: + +```md +{{</* table "fruits" */>}} +``` + + +This will render the following table: + +{{< table "fruits" >}} + +## Table Definitions + +Tables can be defined as: + +* An array of rows. +* A hash with `cols` and `rows` properties. + +When defined as an array, the first row is used as the column headers. +Example: + +```yaml +tables: + fruits: + - ["name", "text"] # <-- this row is used as the column headers + - ["apple", "red"] + - ["banana", "yellow"] + - ["grape", "green"] +``` + + +When defined as a hash, the `cols` and `rows` properties are required. +Here is the same table defined as a hash: + +```yaml +tables: + fruits: + # table columns + cols: ["name", "text"] + + # table rows + rows: + - ["apple", "red"] + - ["banana", "yellow"] + - ["grape", "green"] +``` + + +Defining a table as a hash allows you to specify several additional +table properties. The [Table Properties section](#table-properties) +contains a complete list of available table properties. + +### Table Data Sources + +Table definitions can be stored in two places: + +* [page front matter][front matter] in the `tables` section. +* [site `data` directory][site data] as [JSON][], [TOML][], or [YAML][] + files. + +**Note:** I will use [YAML][] front matter for the examples below. + +#### Front Matter Tables + +Here is an example of a table defined in the page [front matter][]: + +##### Front Matter +```yaml +--- +# ... other front matter omitted ... + +tables: + # example of table defined as arrays + cols_as_array: + # table columns (required) + cols: ["name", "text"] + + # table rows (required) + rows: + - ["apple", "red"] + - ["banana", "yellow"] + - ["grape", "green"] +--- +``` + + +##### Content + +```md +{{</* table "cols_as_array" */>}} +``` + + +##### Result + +{{< table "cols_as_array" >}} + +#### Site Data Tables + +Tables can also be defined in the [site `data` directory][site data] by +using the two-argument version of the `table` shortcode. + +Here is an example of the two argument version of of the `table` +shortcode: For example: + +```md +{{</* table "table_shortcode_examples" "fruits" */>}} +``` + + +In the example above, the `table` shortcode will look for the table data +in the file `data/tables/table_shortcode_examples/fruits.yaml`. + +##### Data File + +Contents of `data/tables/table_shortcode_examples/fruits.yaml`. + +```yaml +--- +# table columns (required) +cols: ["name", "text"] + +# table rows (required) +rows: + - ["apple", "red"] + - ["banana", "yellow"] + - ["grape", "green"] +``` + +##### Content + +```md +{{</* table "table_shortcode_examples" "fruits" */>}} +``` + + +##### Result + +{{< table "table_shortcode_examples" "fruits" >}} + + +### Table Captions + +This section contains an example of specifying a table with a `caption` +property. + +#### Front Matter + +Here is an example table definition with a `caption` property: + +```yaml +--- +# ... other front matter omitted ... + +tables: + table_caption: + # table caption + caption: "an example caption" + + # table columns + cols: ["name", "text"] + + # table rows + rows: + - ["apple", "red"] + - ["banana", "yellow"] + - ["grape", "green"] +--- +``` + + +#### Content + +Here is the corresponding table short code from the page content: + +```md +{{</* table "table_caption" */>}} +``` + + +#### Result + +Here is the resulting table: + +{{< table "table_caption" >}} + +### Table Properties + +Here is a complete list of available table properties: + +{{< table "table_props" >}} + +## Column Definitions + +Table columns can be defined in two ways: + +* As an array of values. +* As an array of hashes. + +Defining columns as an array of hashes allows you to specify several +additional properties for each column. The [Column +Properties section](#column-properties) contains a complete list of +available column properties. + +### Columns Defined as an Array of Values + +Here is an example of a table where the columns are defined as an array +of values. + +#### Front Matter + +Front matter for table with columns are defined with an array of values. + +```yaml +--- +# ... other front matter omitted ... + +tables: + # example of table with columns defined as an array of values + cols_as_array: + # table columns (required) + cols: ["name", "text"] + + # table rows (required) + rows: + - ["apple", "red"] + - ["banana", "yellow"] + - ["grape", "green"] +--- +``` + + +#### Page Content + +Here is the corresponding table shortcode reference from the page +content for the table defined in the previous section: + +```md +{{</* table "cols_as_array" */>}} +``` + + +#### Result + +Here is the result: + +{{< table "cols_as_array" >}} + +### Columns Defined as an Array of Hashes + +Here is an example of a table where the columns are defined as an array +of hashes. + +#### Front Matter + +```yaml +--- +# ... other front matter omitted ... + +tables: + # example where columns are defined as hashes + hashes: + # table columns + # the `id` property + cols: + - id: "name" + name: "Name" + - id: "text" + name: "Text" + + # table rows (required) + rows: + - name: "apple" + text: "red" + - name: "banana" + text: "yellow" + - name: "grape" + text: "green" +--- +``` + + +#### Content + +```md +{{</* table "hashes" */>}} +``` + + +#### Result + +{{< table "hashes" >}} + +### Column Tooltips + +Use the `tip` property of columns to specify the `title` and +`aria-lable` of columns. + +#### Front Matter + +```yaml +--- +# ... other front matter omitted ... + +tables: + column_tooltips: + # table columns (required) + cols: + - id: "name" + name: "Name" + tip: "The name of the fruit." + - id: "text" + name: "Text" + tip: "A brief description of the fruit." + + # table rows (required) + rows: + - name: "apple" + text: "red" + - name: "banana" + text: "yellow" + - name: "grape" + text: "green" +--- +``` + + +#### Content + +```md +{{</* table "column_tooltips" */>}} +``` + + +#### Result + +{{< table "column_tooltips" >}} + +**Hint:** Hover over the column headers and table cells to show the +custom tooltip. + +### Column Alignment + +Use the `align` property of columns to specify column alignment. + +Valid values of the `align` property are: +* `left` +* `center` +* `justify` +* `right` + +The rest of this section contains an example of a table with a +right-aligned second column. + +#### Front Matter + +```yaml +--- +# ... other front matter omitted ... + +tables: + # table + column_alignment: + # table columns (required) + cols: + - id: "name" + name: "Name" + align: "left" + - id: "text" + name: "Text" + align: "right" + + # table rows (required) + rows: + - name: "apple" + text: "red" + - name: "banana" + text: "yellow" + - name: "grape" + text: "green" +--- +``` + + +#### Content + +```md +{{</* table "column_alignment" */>}} +``` + + +#### Result + +{{< table "column_alignment" >}} + +### Column Properties + +Here is a complete list of the available column properties: + +{{< table "col_props" >}} + +## Row Definitions + +Rows are defined as: + +* An array of values. +* Hashes. This is **required** if columns are [defined as an + array of hashes](#columns-defined-as-an-array-of-hashes). + +Defining a rows with hashes allows you to specify several additional +properties. The [Row Properties section](#row-properties) contains a +complete list of available properties. + +The `<tr>` elements generated by this shortcode are annotated with +several additional [HTML][] attributes. See the [Row HTML Attributes +section](#row-html-attributes) for a complete list of [HTML][] +attributes. + +### Row Properties + +Here is a complete list of available properties for rows defined as +hashes: + +{{< table "row_props" >}} + +### Row HTML Attributes + +Generated `<tr>` elements for rows are annotated with the following +attributes: + +{{< table "row_attrs" >}} + +**Note:** For rows defined as an array of values, only the `data-tr_y` +attribute is generated. + +## Cell Definitions + +Row cells can be specified as: + +* a value +* a hash + +Defining cells with hashes allows you to specify several additional +properties. The [Cell Properties section](#cell-properties) contains a +complete list of available properties. + +The `<td>` elements generated by this shortcode for table cells are +annotated with several additional [HTML][] attributes. See the [Cell +HTML Attributes section](#cell-html-attributes) for a complete list of +[HTML][] attributes. + +### Cells Defined as Values + +Here is an example of a table with the cells defined as values. + +#### Front Matter + +```yaml +--- +# ... other front matter omitted ... + +tables: + # example of table with cells as values + cells_as_values: + cols: + - id: "name" + name: "Name" + - id: "text" + name: "Text" + align: "right" + + rows: + - name: "apple" + text: "red" + - name: "banana" + text: "yellow" + - name: "grape" + text: "green" +``` + + +#### Content + +Here is the corresponding shortcode in the page content: + +```md +{{</* table "cells_as_values" */>}} +``` + + +#### Result + +Here is the generated table: + +{{< table "cells_as_values" >}} + +### Cells Defined as Hashes + +Here is an example of a table with a single cell defined as a hash. + +#### Front Matter + +```yaml +--- +# ... other front matter omitted ... + +tables: + # example of table a single cell defined cells as a hash + cells_as_hashes: + cols: + - id: "name" + name: "Name" + - id: "text" + name: "Text" + align: "right" + + rows: + - name: "apple" + text: "red" + - name: "banana" + text: "yellow" + - name: "grape" + text: + # cell with custom alignment and tooltip + val: "green" + align: "left" + tip: "This cell has a custom tooltip." +``` + + +#### Content + +Here is the corresponding shortcode in the page content: + +```md +{{</* table "cells_as_hashes" */>}} +``` + + +#### Result + +Here is the generated table: + +{{< table "cells_as_hashes" >}} + +**Hint:** Hover over the word `green` to see the custom tooltip. + +### Cell Markup + +Cell values can use the following markup: + +* [Markdown][] (default) +* [HTML][], by specifying the cell as a hash and setting the `html` + property to `true`. + +#### Markdown + +This section contains is an example table with a cell that uses +[Markdown][] markup. + +**Note:** [Markdown][] links in cell values **cannot be specified** +using `[name][code]` syntax; instead they must use one of the following +[Markdown][] link syntaxes: + +* `[name](full_url)` +* `[name](full_url "tooltip")` + +##### Front Matter + +```yaml +--- +# ... other front matter omitted ... + +tables: + # example of table with cells using markdown markup + cell_markup_markdown: + cols: + - id: "name" + name: "Name" + - id: "text" + name: "Text" + + rows: + - name: "apple" + text: "*red*" # italics + - name: "banana" + text: "**yellow**" # bold + - name: "grape" + text: "[green](https://pablotron.org/ \"my favorite site\")" # link +``` + +##### Content + +Here is the corresponding shortcode in the page content: + +```md +{{</* table "cell_markup_markdown" */>}} +``` + + +##### Result + +Here is the generated table: + +{{< table "cell_markup_markdown" >}} + +#### HTML + +You can render cell values using [HTML][] markup by specifying the cell +as a hash and then setting the `html` property of the cell to `true`. + +This section contains an example table containing cells using [HTML][] +markup. + +##### Front Matter + +```yaml +--- +# ... other front matter omitted ... + +tables: + # example of table with cells using html markup + cell_markup_html: + cols: + - id: "name" + name: "Name" + - id: "text" + name: "Text" + + rows: + - name: "apple" + # cell value using HTML markup for italics + text: + val: "<i>red</i>" + html: true + - name: "banana" + # cell value using HTML markup for bold + text: + val: "<b>yellow</b>" # bold + html: true + - name: "grape" + # cell value using HTML markup for a link + text: + val: "<a href='https://pablotron.org/' title='my favorite site'>green</a>" + html: true +``` + + +##### Content + +Here is the corresponding shortcode in the page content: + +```md +{{</* table "cell_markup_html" */>}} +``` + + +##### Result + +Here is the generated table: + +{{< table "cell_markup_html" >}} + +### Cell Properties + +Here is a complete list of available properties for cells defined as +hashes: + +{{< table "cell_props" >}} + +### Cell HTML Attributes + +Generated `<td>` elements for table cells are annotated with the +following attributes: + +{{< table "cell_attrs" >}} + +**Note:** For cells defined as a value rather than a hash, only +following attributes are generated for `<td>` elements: + +* `data-td_x` +* `title` (set to the column name) +* `aria-label` (set to the column name) + +## Overwriding Table Configuration + +Column and cell alignment is rendered using [CSS][] classes rather than +inline `style` attributes. + +The default `align` to [CSS][] `class` mapping is as follows: + +{{< table "align_classes" >}} + +These classes work out of the box with [Bulma][]. If you're using +another framework, you can change the [CSS class][css] +configuration on a per-table, per-page, or per-site basis. + +See the [Table Configuration Properties +section](#table-configuration-properties "Table Configuration Properties") +for a full list of available table configuration properties. + +### Table Override + +Use the `config` property to override the table configuration for a +specific table. + +#### Front Matter + +```yaml +--- +# ... other front matter omitted ... + +tables: + # table with custom config that renders right-aligned text as bold + table_with_config_override: + # table config override that renders right-aligned text as bold + config: + table_class: "table" + align_left: "has-text-left" + align_center: "has-text-centered" + align_justify: "has-text-justified" + align_right: "has-text-weight-bold" + + cols: + - id: "name" + name: "Name" + - id: "text" + name: "Text" + align: "right" + + rows: + - name: "apple" + text: "red" + - name: "banana" + text: "yellow" + - name: "grape" + text: "green" +``` + + +#### Content + +Here is the corresponding shortcode in the page content: + +```md +{{</* table "table_with_config_override" */>}} +``` + + +#### Result + +Here is the generated table: + +{{< table "table_with_config_override" >}} + +### Page Override + +Use the `table_config` property in the [page front matter][front matter] +to override the configuration for all tables on a page that are +generated with the table shortcode. + +Here is an example page-level table configuration override which +emits a `has-text-weight-bold` class for all table cells with an +alignment set to `justify`: + +```yaml +--- +# ... other front matter omitted ... + +# override config for all tables generated with table shortcode on this +# page so that right-aligned cell values are rendered as bold +table_config: + table_class: "table" + align_left: "has-text-left" + align_center: "has-text-centered" + align_justify: "has-text-weight-bold" + align_right: "has-text-right" +``` + + +### Site Override + +Use the `table_config` parameter in the root `config.toml` to override +the table configuration for all tables across all pages on a site that +are generated with the table shortcode. + +Here is an example overide for [Bootstrap][]: + +```toml +# table shortcode bootstrap override +[params.table_config] + # class to assign to all generated tables + table_class = "table" + + # class for left-aligned column headers and cells + align_left = "text-start" + + # class for centered column headers and cells + align_center = "text-center" + + # class for justified column headers and cells + # (note: doesn't provide a justify alignment class so you + # would need to provide your own) + align_justify = "my-custom-justify-class" + + # class for right-aligned column headers and cells + align_right = "text-right" +``` + + +### Table Configuration Properties + +Here is a full list of available table configuration properties: + +{{< table "table_config_props" >}} + +[site data]: https://gohugo.io/templates/data-templates/#the-data-folder + "Site data directory." +[front matter]: https://gohugo.io/content-management/front-matter/ + "Hugo page metadata." +[css]: https://en.wikipedia.org/wiki/CSS + "Cascading Style Sheets" +[bulma]: https://bulma.io/ + "Bulma CSS framework." +[bootstrap]: https://getbootstrap.com/ + "Bootstrap CSS framework." +[json]: https://json.org/ + "JavaScript Object Notation" +[yaml]: https://yaml.org/ + "YAML Ain't a Markup Language" +[toml]: https://github.com/toml-lang/toml + "Tom's Obvious Markup Language" +[hugo]: https://gohugo.io/ + "Hugo static site generator" +[goldmark]: https://github.com/yuin/goldmark/ + "Goldmark Markdown renderer." +[html]: https://en.wikipedia.org/wiki/HTML + "HyperText Markup Language" +[markdown]: https://en.wikipedia.org/wiki/Markdown + "Markdown markup language" +[hugo-shortcode-table]: https://github.com/pablotron + "hugo-shortcode-table github repository" |