This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/

CheckboxWidget

 2nd April 2022 at 2:36am

Introduction

The checkbox widget displays an HTML <input type="checkbox"> element that is dynamically bound to either:

  • the presence or absence of a specified tag on a specified tiddler
  • the value of a specified field of a specified tiddler

Content and Attributes

The content of the <$checkbox> widget is displayed within an HTML <label> element immediately after the checkbox itself. This means that clicking on the content will toggle the checkbox.

AttributeDescription
tiddlerTitle of the tiddler to manipulate (defaults to the current tiddler)
tagThe name of the tag to which the checkbox is bound
invertTagWhen set to yes, flips the tag binding logic so that the absence of the tag causes the checkbox to be checked
fieldThe name of the field to which the checkbox is bound
listField New in: 5.2.3 The name of the field that contains the list to which the checkbox is bound
index New in: 5.1.14 The index of the tiddler, a DataTiddler, to which the checkbox is bound
be sure to set the tiddler correctly
listIndex New in: 5.2.3 Like index, but treats the value as a list the same way that listField does
filter New in: 5.2.3 A filter whose output determines the checked state of the checkbox
checkedThe value of the field corresponding to the checkbox being checked
uncheckedThe value of the field corresponding to the checkbox being unchecked
defaultThe default value to use if the field is not defined
indeterminateWhether ambiguous values can produce indeterminate checkboxes (see below)
classThe class that will be assigned to the label element
New in: 5.2.3 tc-checkbox is always applied by default, as well as tc-checkbox-checked when checked
actions New in: 5.1.14 A string containing ActionWidgets to be triggered when the status of the checkbox changes (whether it is checked or unchecked)
uncheckactions New in: 5.1.16 A string containing ActionWidgets to be triggered when the checkbox is unchecked
checkactions New in: 5.1.20 A string containing ActionWidgets to be triggered when the checkbox is checked
disabled New in: 5.1.23 Optional, disables the checkbox if set to "yes". Defaults to "no"

Tag Mode

Using the checkbox widget in tag mode requires the tag attribute to specify the name of the tag. The tiddler attribute specifies the tiddler to target, defaulting to the current tiddler if not present.

This example creates a checkbox that flips the done tag on the current tiddler:

<$checkbox tag="done"> Is it done?</$checkbox>

That renders as:

Field Mode

Using the checkbox widget in field mode requires the field attribute to specify the name of the field. The checked and unchecked attributes specify the values to be assigned to the field to correspond to its checked and unchecked states respectively. The default attribute is used as a fallback value if the field is not defined.

This example creates a checkbox that is checked if the field status is equal to open and unchecked if the field is equal to closed. If the field is undefined then it defaults to closed, meaning that the checkbox will be unchecked if the status field is missing.

<$checkbox field="status" checked="open" unchecked="closed" default="closed"> Is it open?</$checkbox><br />''status:'' {{!!status}}

That renders as:


status:

List Mode

Using the checkbox widget in list mode requires the listField attribute to specify the name of a field containing a list. The checked attribute specifies the value that should be present or absent in the list when the checkbox is checked or unchecked respectively. If checked is absent (or empty) but unchecked is present, then the logic will be inverted: the checkbox will be checked when the "unchecked" value is missing from the list, and unchecked when the "unchecked" value is found in the list. If both checked and unchecked are present, the checkbox will work like a toggle, replacing the checked value with the unchecked value and vice-versa. Finally, if neither checked nor unchecked is specified, the checkbox will be checked if the field has anything in it, but unchecked if the field is missing or empty. (This is rarely useful; most of the time you'll want to specify checked or unchecked or both.)

The default attribute is used as a fallback for the checkbox state if the field is not defined.

This example creates a checkbox that is checked if the list field named colors contains green and unchecked if the field contains red. If the field is undefined, or if neither green nor red appears in the field, then it defaults to green, meaning that the checkbox will be checked.

<$checkbox listField="colors" checked="green" unchecked="red" default="green"> Is it green?</$checkbox><br />''colors:'' {{!!colors}}

That renders as:


colors: red orange yellow blue

Try editing the colors field of this tiddler to see how the example changes.

Index Mode

To use the checkbox widget in index mode set the index attribute to the index of a DataTiddler. The checked and unchecked attributes specify the values to be assigned to the index and correspond to its checked and unchecked states respectively. The default attribute is used as a fallback value if the index is undefined.

The example below creates a checkbox that is checked if the index by the name of this tiddler in the tiddler ExampleData is equal to selected and unchecked if the index is an empty string. If the index is undefined then it defaults to an empty string, meaning the checkbox will be unchecked if the index is missing.

<$checkbox tiddler="ExampleData" index=<<currentTiddler>> checked="selected" unchecked="" default=""> Selected?</$checkbox>

That renders as:

Index List Mode

Using the checkbox widget in index list mode requires the listIndex attribute to specify the the index of a DataTiddler containing a list. The checked attribute specifies the value that should be present or absent in the list when the checkbox is checked or unchecked respectively. If checked is absent (or empty) but unchecked is present, then the logic will be inverted: the checkbox will be checked when the "unchecked" value is missing from the list, and unchecked when the "unchecked" value is found in the list. If both checked and unchecked are present, the checkbox will work like a toggle, replacing the checked value with the unchecked value and vice-versa. Finally, if neither checked nor unchecked is specified, the checkbox will be checked if the field has anything in it, but unchecked if the field is missing or empty. (This is rarely useful; most of the time you'll want to specify checked or unchecked or both.)

The default attribute is used as a fallback for the checkbox state if the index is undefined.

The example below creates three checkboxes that each control a different value in an index field of the ExampleData tiddler.


<$set name=indexName filter="[<currentTiddler>addsuffix[ Colors]]" >
<$checkbox tiddler="ExampleData" listIndex=<<indexName>> checked="green" unchecked="red" default="red"> Green or red?</$checkbox> <br/>
<$checkbox tiddler="ExampleData" listIndex=<<indexName>> checked="yellow" unchecked="blue" default="blue"> Yellow or blue?</$checkbox> <br/>
<$checkbox tiddler="ExampleData" listIndex=<<indexName>> checked="orange" unchecked="purple" default="purple"> Orange or purple?</$checkbox> <br />
Colors list: {{{ [[ExampleData]getindex<indexName>] }}}
</$set>

That renders as:




Colors list:

Filter Mode

Using the checkbox widget in filter mode requires the filter attribute to contain a filter whose output will determine the checked state of the checkbox. In filter mode, checking the checkbox will not automatically make changes to any field of any tiddler. Instead, you can use the actions attribute (or checkactions and uncheckactions) to specify what should happen when the checkbox is toggled. It is your responsibility to make sure the actions cause changes to the tiddlers or fields that the filter results depend on, so that the checkbox becomes properly checked or unchecked after the actions have triggered.

If the filter returns an empty result, the checkbox will be unchecked. Otherwise, if the filter result is non-empty, the checkbox will be checked. However, if either the checked or unchecked attributes (or both) are specified, then their values will be looked for in the filter result, instead of considering any non-empty value to mean "checked".

This example creates the same checkbox as in the list mode example, selecting between red and green in the colors list field, but using filters and actions to make the change.

\define checkActions() <$action-listops $field="colors" $subfilter="-red green"/>
\define uncheckActions() <$action-listops $field="colors" $subfilter="red -green"/>
<$checkbox filter="[list[!!colors]]" checked="green" unchecked="red" default="red" checkactions=<<checkActions>> uncheckactions=<<uncheckActions>> > Is "green" in colors?</$checkbox><br />''colors:'' {{!!colors}}

That renders as:


colors: red orange yellow blue

Indeterminate checkboxes

If both the checked and unchecked attributes are specified, but neither one is found in the specified field (or index), the result can be ambiguous. Should the checkbox be checked or unchecked? Normally in such cases the checkbox will be unchecked, but if the indeterminate attribute is set to "yes" (default is "no"), the checkbox will instead be in an "indeterminate" state. An indeterminate checkbox counts as false for most purposes — if you click it, the checkbox will become checked and the checkactions, if any, will be triggered — but indeterminate checkboxes are displayed differently in the browser.

This example shows indeterminate checkboxes being used for categories in a shopping list (which could also be sub-tasks in a todo list, or many other things). If only some items in a category are selected, the category checkbox is indeterminate. You can click on the category checkboxes to see how indeterminate states are treated the same as the unchecked state, and clicking the box checks it and applies its check actions (in this case, checking all the boxes in that category). Try editing the fruits and vegetables fields on this tiddler and see what happens to the example when you do.

\define check-all(field-name:"items") <$action-listops $field="selected-$field-name$" $filter="[list[!!$field-name$]]" />
\define uncheck-all(field-name:"items") <$action-listops $field="selected-$field-name$" $filter="[[]]" />

<$checkbox filter="[list[!!selected-fruits]count[]]" checked={{{ [list[!!fruits]count[]] }}} unchecked="0" checkactions=<<check-all fruits>> uncheckactions=<<uncheck-all fruits>> indeterminate="yes"> fruits</$checkbox>
<ul style="list-style: none">
<$list variable="fruit" filter="[list[!!fruits]]">
<li><$checkbox listField="selected-fruits" checked=<<fruit>>> <<fruit>></$checkbox></li>
</$list>
</ul>
<$checkbox filter="[list[!!selected-vegetables]count[]]" checked={{{ [list[!!vegetables]count[]] }}} unchecked="0" checkactions=<<check-all vegetables>> uncheckactions=<<uncheck-all vegetables>> indeterminate="yes"> veggies</$checkbox>
<ul style="list-style: none">
<$list variable="veggie" filter="[list[!!vegetables]]">
<li><$checkbox listField="selected-vegetables" checked=<<veggie>>> <<veggie>></$checkbox></li>
</$list>
</ul>

<p>Selected veggies: {{!!selected-vegetables}}<br/>
Selected fruits: {{!!selected-fruits}}</p>

That renders as:

Selected veggies:
Selected fruits: