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.
|field |The name of the field to which the checkbox is bound |
|index|<<.from-version "5.1.14">> The index of the //tiddler//, a [[DataTiddler|DataTiddlers]], to which the checkbox is bound<<.tip "be sure to set the //tiddler// correctly">>|
|actions |<<.from-version "5.1.14">> A string containing ActionWidgets to be triggered when the status of the checkbox changes (whether it is checked or unchecked) |
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:
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.
<<wikitext-example-without-html """<$checkbox field="status" checked="open" unchecked="closed" default="closed"> Is it open?</$checkbox><br>''status:'' {{!!status}}""">>
!! Index Mode
To use the checkbox widget in index mode set the ''index'' attribute to the index of a [[DataTiddler|DataTiddlers]]. 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.
This example of using the `actions` attribute shows both the [[Action Set Field Widget|ActionSetFieldWidget]] and [[Action Send Message Widget|ActionSendMessageWidget]] to demonstrate two actions.
The [[Set Widget|SetWidget]] uses a filter value to set the value of variable `tag`. The [[Action Send Message Widget|ActionSendMessageWidget]] joins all the tags into one large tag. The [[Action Set Field Widget|ActionSetFieldWidget]] appends the tags as individual tags. In this example, the [[Field Mangler Widget|FieldManglerWidget]] is required for the [[Action Send Message Widget|ActionSendMessageWidget]] but not for [[Action Set Field Widget|ActionSetFieldWidget]]. Be aware that the action occurs whether you check or uncheck.
It is often necessary to use triple quotes with the `actions` attribute. Alternatively, the attribute can be assigned directly from a variable with `actions=<<my-actions>>`.
