Dynamic table concept

A dynamic table is a table its rows and columns created dynamically from tiddlers selected by some certain criteria. So, when a tiddler in the wiki meets such criteria will automatically create a new row in the table.

Rows and columns

In a dynamic table a row also called a record is a tiddler and a column is a field or index of that tiddler. So in brief

• rows or records are created by selected tiddlers
• columns are created from fields or indexes of those tiddlers
• cell in row i and column j in the table is the value from a field/index created column j and a tiddler created row i

Dynamic table mechanism

A dynamic table is created by a dedicated macro as below

• Use a filter to select some tiddlers like [tag[foo]]
• Use a filter to select fields or indexes like "title tags created" or [prefix[tb]] which select all fields or indexes start with tb
• Call the appropriate macro using above filters and pass them to appropriate macro parameter

Dynamic table macros

Shiraz plugin has two macros to create a dynamic table

1. macro table-fd to create dynamic tables from tiddlers fields
2. macro table-id to create dynamic tables from data tiddlers indexes

Features

Dynamic tables have several features including

• sort by columns in both direction (ascending and descending)
• inline edit of cells (fields or indexes of tiddlers)
• delete a row (e.g a record or a tiddler )
• delete all records (tiddlers) with double confirmation message
• add dynamically new fields or indexes to tiddlers (records)
• display fields or indexes (columns) with specified format through templates
  • title, tags, created, modified, email fields use special format for displaying data
  • templates can be added to display new fields or indexes

Reference

Dynamic tables in Shiraz is based on the great plugin TiddlyTables by Alan Aldrich, so all kodous goes to Alan.

Dynamic tables is a very simple with limited features comparing to TiddlyTables. Shiraz dynamic tables has some features not available in TiddlyTables 0.6.13 (at the time of release Dec 2019) like

• inline editor
• data tiddler support
• independency from host tiddler (e.g. having many tables in one tiddler)
• minimum settings
• numerical summary

These make Shiraz dynamic tables a simple and easy to use limited version of Tiddlywiki dynamic tables.

Dynamic table from fields

The table-fd macro creates dynamic tables from tiddler fields. Rows (or recoreds) in such tables are constructed from tiddlers and columns from fields of those tiddlers. Each field creates a column in the table.

Syntax

<<table-fd filter:"" fields:"" sortOp:"sort" caption:"" class:"" stateTiddler:"" footerRows:"">>

Content and attributes

Remarks

• The stateTiddler parameter can be ignored if one dynamic table is created per tiddler. When there are several dynamic tables in the same tiddler, a unique state tiddler is required for each table to store different states used for proper operation.
• The table-fd macro creates a state tiddler by calling the qualify macro and prefixed them with $:/temp/dynamictables/, so you can pass value like table01 as stateTiddler parameter.
• For numerical summary see demo/dynamic-tables-numerical-summary

Special column

There are special columns display contents in special format like

• title to display tiddler title as a link
• created to display the creation date of tiddler
• modified to display the modification date of tiddler
• tags to display the tags of tiddler

Using column template it possible to create more special column. One example is the email column! It shows the content as a mailto link.

Display tiddler text

Passing the tbl-expand as a special column creates an extra column in displayed table. It adds a button to each table row, on click the text of tiddler is displayed in a new row. See examples.

Edit mode and view mode

Dynamic tables in Shiraz have two modes for displaying tables:

• edit mode: one can directly edit the cells
• view mode: the rendered wikified results are displayed

To toggle between the edit and view mode simple click on the and shown at the upper left corner of table

Sort by column

A dynamic table can be sorted using column data. To sort a table simply click on the column header. To toggle between ascending/descending order click again on the column header and note to arrows and appears in column header.

Example i

Create a simple dynamic table from tiddlers tagged with sample and use title, email, created and tag fields.

<<table-fd filter:"[tag[sample]]" fields:"title email created tags" stateTiddler:"exmp01" caption:"''Table 1. Dynamic table example''">>

Example ii

Repeat Example i and add table-center and thead-dark as table classes. Also add two other fields fa and fb

<<table-fd filter:"[tag[sample]]" fields:"title fa fb email created tags" stateTiddler:"exmp02" class:"table-center thead-dark" caption:"''Table 2. Dynamic table example''">>

Example iii

Repeat Example i and add w-100 (to extend table width to 100% of parent container) and thead-dark as table classes. Also add three other fields fa and fb and the special column tbl-expand to show the toggle button for displaying the text field

<<table-fd filter:"[tag[sample]]" fields:"tbl-expand title fa fb email created tags" stateTiddler:"exmp03" class:"w-100 thead-dark" caption:"''Table 3. Dynamic table example''">>

Use table classes

Shiraz has several table classes can be used for dynamic tables see Table Classes. It is possible to create user customized CSS classes and pass them to table-fd macro.

The below example uses float right (float-right) which has 75% of tiddler width (w-75), with left margin setting (ml-3) and hover effect (table-hover-cyan) and info conceptual color header (thead-info).

<<table-fd filter:"[tag[sample]]" fields:"tbl-expand title fa fb email created tags" stateTiddler:"exmp04" class:"float-right ml-3 w-75 table-hover-cyan thead-info" caption:"''Table 4. Dynamic table example''">>

Dynamic table from data tiddlers macro

The table-id macro creates dynamic tables from data tiddler indexes. Rows (or records) in such tables are constructed from tiddlers and columns from indexes of those tiddlers. Each index creates a column in the table.

Both type of data tiddlers are supported

• dictionary tiddler
• json data

Syntax

<<table-fi filter:"" indexes:"" sortOp:"sort" caption:"" class:"" stateTiddler:"" footerRows>>

Content and attributes

Remarks

• The stateTiddler parameter can be ignored if one dynamic table is created per tiddler. When there are several dynamic tables in the same tiddler, a unique state tiddler is required for each table to store differnt states used for proper operation.
• The table-id macro creates a state tiddler by calling the qualify macro and prefixed them with $:/temp/dynamictables/, so you can pass value like table01 as stateTiddler parameter.
• For numerical summary see demo/dynamic-tables-numerical-summary

Special column

There are special columns display contents in special format like

• title to display tiddler title as a link
• created to display the creation date of tiddler
• modified to display the modification date of tiddler
• tags to display the tags of tiddler

Using column template it possible to create more special column. One example is the email column! It shows the content as a mailto link.

Display tiddler text

Passing the tbl-expand as a special column creates an extra column in displayed table. It adds a button to each table row, on click the text of tiddler is displayed in a new row. See examples.

Edit mode and view mode

Dynamic tables in Shiraz have two modes for displaying tables:

• edit mode: one can directly edit the cells
• view mode: the rendered wikified results are displayed

To toggle between the edit and view mode simple click on the and shown at the upper left corner of table

Sort by column

A dynamic table can be sorted using column data. To sort a table simply click on the column header. To toggle between ascending/descending order click again on the column header and note to arrows and appears in column header.

Example i

Create a simple dynamic table from tiddlers tagged with data and use title and tags as special columns, and midterm, homework indexes.

<<table-id filter:"[tag[data]]" indexes:"title tags midterm homework" stateTiddler:"exmp01" caption:"''Table 1. Dynamic table from data tiddler''">>

Example ii

Repeat Example i and add table-center and thead-dark as table classes. Also display term paper and final and remove special column tags. Note that term paper has spaces in title and should be passed as [[term paper]].

<<table-id filter:"[tag[data]]" indexes:"title midterm homework [[term paper]] final"  stateTiddler:"exmp02" class:"table-center thead-dark" caption:"''Table 2. Dynamic table from data tiddler''">>

Example iii

Repeat Example ii and add w-100 (to extend width to 100% of parent container) and thead-dark as table classes. Also add the special column tbl-expand to show toggle button for displaying the text field.

<<table-id filter:"[tag[data]]" indexes:"tbl-expand title midterm homework [[term paper]] final"  stateTiddler:"exmp03" class:"w-100 thead-dark" caption:"''Table 3. Dynamic table from data tiddler''">>

Use table classes

Shiraz has several table classes can be used for dynamic tables see Table Classes. It is possible to create user customized CSS classes and pass them to table-id macro.

The below example uses float right (float-right) which has 75% of tiddler width (w-75), with left margin setting (ml-3) and hover effect (table-hover-yellow) and warning conceptual color header (thead-warning).

<<table-id filter:"[tag[data]]" indexes:"tbl-expand title midterm homework [[term paper]] final"  stateTiddler:"exmp04" class:"float-right w-75 ml-3 table-hover-yellow thead-warning" caption:"''Table 4. Dynamic table from data tiddler''">>

Dynamic table and numerical summary

It is desired to be able to have summary rows to show some simple calculation on columns with numerical values. For example a column shows the scores of students for Chemistry course and one likes to compute the maximum, minimum, average, and median.

Numerical macros

Shiraz dynamic tables support the below numerical macros

• count: number of records in a column
• maxall: maximum value in a column
• minall: minimum value in a column
• sum: sum of all values in a column
• product: products of all values in a column
• average: the arithmetic mean of all values in a column
• median: the value separating the higher half from the lower half of numerical data in a column

How to use

In a dynamic table containing footer rows, go to edit mode, in a footer cell of a desired column call the proper macro. For example to calculate average, enter <<average>>. The below examples show how numerical summary can be inserted in footer rows of dynamic tables.

Example i: dynamic table from fields

This example shows how numerical summaries can be added at the footer of a dynamic table created from tiddlers fields. In this example seven footer rows are give.

<$macrocall $name=table-fd filter="[tag[sample]]" class="table-hover-yellow" fields="title fa fb caption" stateTiddler="nella" caption="''Table 1. Dynamic table example''" footerRows="7"/>

Example ii: dynamic table from indexes

This example demonstrate the use of numerical summary for a dynamic table from data tiddlers. It uses four footer rows to show, average, max, min, and median of numerical data in the column.

<<table-id filter:"[tag[data]]" indexes:"title midterm homework" stateTiddler:"lola" caption:"''Table 2. Dynamic table from data tiddler''" footerRows:"4">>

When using tabs macro or transclusion feature in Tiddlywiki, the definition of currentTiddler variable will change and it depends to the scope.

Dynamic tables uses currentTiddler variable to create a state tiddler to store the numerical summaries. When a tiddler contains a dynamic table is transcluded or used in a tabs macro this causes error and dynamic table macros table-fd and table-id cannot show the numerical summary correctly.

To overcome these missuses do as bellow

Use in tabs macro

Tiddlywiki itself recommend to use template with tabs macro, if one needs to use transclusion. See tabs macro. Simple pass the below template tiddler to tabs macro

$:/tabs/template

<$tiddler tiddler=<<currentTab>>>
<$transclude mode="block" />
</$tiddler>

In this tutorial, Tutorial Dynamic Tables has been created using this approach, it looks like below:

<<tabs tabsList:"[tag[dynamic-table]!tag[advanced]prefix[demo]]" default:"demo/dynamic-table-concept" class:"tc-horizontal" template:"$:/tabs/template">>

Use in simple transclusion

When a tiddler containing a dynamic table is transcluded, the transclusion causes the scope of currentVariable changes, to keep it consistent, do as below

• method i

  Use the $tiddler widget and wrap the transclusion. The tidname referes to the tiddler title contains the dynamic tables.

  <$tiddler tiddler="tidname">
  <$transclude />
  </$tiddler>

• method ii

  Use the $list widget and wrap the transclusion. The tidname referes to the tiddler title contains the dynamic tables.

  <$list filter="tidname">
  <$transclude />
  </$list>

See examples at examples/dynamic-tables/transclusion.

This demo shows how to customize the dynamic table footer when numerical summary is used.

The CSS selector for customizing the footer in dynamic tables is shiraz-dtable-footer which is given in $:/plugins/kookma/shiraz/styles/dynamic-tables

Customize footer globally

Simply create a new tiddler tagged with $:/tags/Stylesheet and set the desired properties. This way one can globally changes and customizes the feel and look of dynamic tables. For example to have red border and bold text do as below:

• create a tiddler
• tag with $:/tags/Stylesheet
• put the below as tiddler text

  .shiraz-dtable-footer tr td{
  font-weight:bold;
  color:red;
  }

Customize footer locally

In the tiddler containg the dynamic table, use the style tag and set the desired properties for shiraz-dtable-footer CSS selector. It is recommended to define a new class to prevent this customization applied to other tiddlers containing dynamic tables and at the same time are open in story river. See the below example.

Example

Here a dynamic table footer is customized using the local style tag. A new class is defined here to prevent other dynamic tables in tiddlers opened in storu river affected.

<$macrocall $name=table-fd filter="[tag[student]]" class="my-footer-class" fields="caption score hospitality" stateTiddler=demo2 footerRows="2"/>

<style>
.my-footer-class .shiraz-dtable-footer tr td{
font-style:oblique;
color:maroon;
background:#FFFFDE;
}
</style>

Remarks

the local class sets font color, style and background

the new class is passed through class to table-fd macro

The numerical summaries inserted in dynamic tables footer actually are some helper macros defined in:

• $:/plugins/kookma/shiraz/macros/dtables/table-fd-utility for table-fd
• $:/plugins/kookma/shiraz/macros/dtables/table-id-utility for table-id

These macros can be overloaded locally or new macros can be defined and used.

Custom macro for numerical summary

To define a custom macro, use the following definitions

• the inputFilter variable holds the dynamic table filter
• the currentColumn variable holds the column in which calculation is performed

Example

For example to claculate the 0.25 of sum of all values in a column a new macro can be defined locally as below:

\define quartersum-fd()
<$text text={{{ [subfilter<inputFilter>has<currentColumn>get<currentColumn>sum[]multiply[0.25]] }}}/>
\end

\define quartersum-id()
<$text text={{{ [subfilter<inputFilter>getindex<currentColumn>sum[]multiply[0.25]] }}}/>
\end

Note

The above macros are defined in the current tiddler and are locally available

When table-fd is used the fields are used to create a column.

When table-id is used the indexes are used to create a column.

So, different macros are required to be used with table-fd and table-id.

Then call it in a new dynamic table created using table-fd or table-id. Edit the below tables to see how they are used.

A task manager example

This demo demonstrate how Shiraz dynamic tables can be used to create a simple but powerful task manager. To implement the task manager example, four new column templates are required, these are

• due-date, this supports html5 colander and due date can be set in the edit mode
• priority, a drop down menu to select among the predefined priority
• status, a drop down menu to select among the predefined status

and a special column template, called tbl-checkbox which has two parts:

• header template
• body template

The task manager example only works with table-fd but records (task tiddlers) can be any type of tiddlers.

Example

To create a task manager using the shiraz dynamic table do as below

• create some task tiddlers
  • tag them with task
  • add required fields e.g. description, priority, status, and due-date
• in a desired tiddler create the task manager by calling the table-fd macro as below

  <$macrocall $name=table-fd filter="[tag[task]]" fields="tbl-checkbox tbl-expand tbl-delete title description priority status due-date tags" class="w-100" stateTiddler="your-state-tid"/>

The below example shows a simple task manager.

How it works

• After creating the task manager table, one can go to edit mode and change different parameters like status, priority, due date, description, main body (text field) etc.
• To change the a task to complete status, use the checkbox located in the same row. This adds a done tag and change status to complete
• To set all task to complete, use the checkbox in the header, this not only adds a done tag to all tiddlers, but also change the status of all tasks to complete.

Remark

Unchecking the checkboxes, including the header checkbox remove the done tag from tasks and reset the status to rework.

Column templates

A column template is tiddler contains preset format and script to display a content like fields, and indexes. For details on how templates work see Tiddlywiki template tiddlers.

Dynamic table uses templates for displaying the contents of fields and indexes. There are two type of column templates

• header template, controls the format and actions in column header
• body template, controls the format and actions in column cell

For example to display the created date of a tiddler (record), a template like below is used

$:/plugins/kookma/shiraz/templates/dtable-body/created

<td>
<$view tiddler=<<currentRecord>> field=<<currentColumn>> format="date" template="YYYY.0MM.0DD"/>
</td>

How to create a custom template

Dynamic table column templates have the below specifications:

• a template is a tiddler tagged with $:/tags/DynamicTable/Template
• a template has one of the below suffixes in its title
  • dtable-header/$(currentColumn)$ for header templates
  • dtable-fieldbody/$(currentColumn)$ for body templates in table-fd macro which creates dynamic tables from fields
  • dtable-indexbody/$(currentColumn)$ for body templates in table-id macro which creates dynamic tables from indexes

The template shall process two modes

• edit mode which is simply uses an $edit-text
• view mode or read mode which contains script how to display the content.

Template also must aware to toggle to view mode if a column is used for sorting table.

Example

The below email template is used to display emails in dynamic tables from fields. It contains

• a part to display email in edit mode
  • this include a section to display email in view mode, if table is sorted by email
• a part to display email in view mode
  • this creates a mailto link

$:/plugins/kookma/shiraz/templates/dtable-fieldbody/email

\define display-email-address()
<a class="tc-tiddlylink-external" href="mailto:$(currentRecord)$!!$(currentColumn)$" rel="noopener noreferrer" target="_blank">
<$transclude tiddler=<<currentRecord>> field=<<currentColumn>> mode="inline" />
</a>
\end

<$reveal type="nomatch" stateTitle=<<tempTableEdit>> stateIndex="mode" text="edit" tag="td">
<<display-email-address>>
</$reveal>
<$reveal type="match" stateTitle=<<tempTableEdit>> stateIndex="mode" text="edit" tag="td">
<!--check if the current column is not selected for sorting-->
<$list filter="[<tempTableSort>getindex[sortIndex]match<currentColumn>]" variable=ignore
emptyMessage="""<$edit-text tiddler=<<currentRecord>> field=<<currentColumn>> tag="input" class="shiraz-dtable-textbox"/>"""
>
<<display-email-address>>
</$list>
</$reveal>