mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-09-29 23:40:45 +00:00
e28af8d594
* Docs for CheckboxWidget list and filter modes
This documents the `listField` and `filter` attributes.
* Tests for checkbox widget list mode
* Implement checkbox list mode
* WIP on implementing filter attr for checkboxes
* Improve CheckboxWidget documentation
* Refactor checkbox tests: move function to top
The big findNodeOfType function belongs at the top of the describe
block, so that the checkbox tests are more compact and easy to read.
* Move checkbox widget tests to end of file
The checkbox widget tests are long and involved, so we'll move them to
the end of the file so they aren't a huge block of code you need to read
past to find the next test.
* Improve formatting of CheckboxWidget docs
The \define() calls that are short enough to fit on one line should be
put on one line, for readability. The ones that are quite long have been
kept on multiple lines, for readability.
* Added more passing tests for checkbox widget
* Add some failing tests for checkbox widget
The filter mode where neither checked nor unchecked is specified (in
which case an empty filter result means false and a non-empty result
means true) is not working yet.
* Make failing tests pass
* Uncomment (and improve) test for field mode
We're now ready to start working on making this test pass. (There was
also one small mistake in the test, which this commit corrects).
* All tests now passing
* No indeterminate checkboxes in simple modes
The simple checkbox modes (field and index) should not produce
indeterminate checkboxes. That should be reserved for the advanced modes
(list and filter).
* Minor improvement to unit tests
* Allow indeterminate checkboxes in list and filter modes
This change may require some tweaks to the unit tests to be able to test
it properly.
* Slightly easier to read tests
* Two more tests for list mode
* Greatly simplify unit test code
Turns out there's no need to jump through Object.getPrototypeOf hoops.
* Minor simplification of unit test
* Add tests for indeterminate in list & filter modes
With this, the set of tests is complete.
* More tests to specify list mode behavior
* Unfocus tests so all tests run
* Update docs to say "new in 5.2.3" insetad of 5.2.2
* Move checkbox widget tests into their own file
The test-widget.js file was getting too long with all the checkbox
tests added, so we'll move the checkbox tests into their own file.
* Add checkbox widget tests for index mode
This commit also adds tests for index list mode (with a listIndex
attribute that will parallel the listField attribute) but leaves them
commented out because they don't pass yet: the code that implements the
listIndex attribute hasn't been written yet).
* Add listIndex attribute to checkbox widget
* Remove code that lets checkboxes be indeterminate
This reverts commit 6afcb151be. We will
add this code back in a later PR.
* Remove indeterminate tests for checkbox widget
We're currently not allowing indeterminate checkboxes, so there's no
need for the tests that check for them.
* Document listIndex attribute of CheckboxWidget
* adds class tc-checkbox-checked when checked
* equivalent to #2182 (RadioWidget)
* also applies `tc-checkbox` to checkboxes by default, always
* Move macro definitions inside example text
Since the wikitext-example-without-html macro creates a new parsing
context, it's safe to have macro definitions inside it. That makes these
examples a lot easier to write, and to read.
* Remove all mention of indeterminate checkboxes
Also improve the documentation a little bit: mention what happens in
list mode if neither checked nor unchecked is specified.
* Move filter mode to bottom of checkbox docs
The `filter` attribute should be under both `listField` and `listIndex`
rather than being between them. The documentation for filter mode should
similarly be after the `listIndex` documentation.
* Improve docs for `class` attr of checkbox widget
This brings the wording of the `class` attribute more in line with how
it's worded in the RadioWidget docs.
* Fix bug with list tiddlers
If neither checked nor unchecked was specified, then the behavior should
be "empty = false, non-empty = true". But if *both* are specified yet
neither is found, then the checkbox should be unchecked (false). It had
been falling through to the "non-empty = true" behavior, which was wrong.
* Improve listIndex example of checkbox widgets
* Remove unused function from test-widget.js
Co-authored-by: Tobias Beer <beertobias@gmail.com>
103 lines
9.5 KiB
Plaintext
103 lines
9.5 KiB
Plaintext
caption: checkbox
|
|
created: 20131024141900000
|
|
modified: 20220402023600000
|
|
tags: Widgets TriggeringWidgets
|
|
colors: red orange yellow blue
|
|
title: CheckboxWidget
|
|
type: text/vnd.tiddlywiki
|
|
|
|
! 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.
|
|
|
|
|!Attribute |!Description |
|
|
|tiddler |Title of the tiddler to manipulate (defaults to the [[current tiddler|Current Tiddler]]) |
|
|
|tag |The name of the tag to which the checkbox is bound |
|
|
|invertTag |When set to ''yes'', flips the tag binding logic so that the absence of the tag causes the checkbox to be checked |
|
|
|field |The name of the field to which the checkbox is bound |
|
|
|listField |<<.from-version "5.2.3">> The name of the field that contains the list 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">>|
|
|
|listIndex |<<.from-version "5.2.3">> Like <<.attr index>>, but treats the value as a list the same way that <<.attr listField>> does |
|
|
|filter |<<.from-version "5.2.3">> A filter whose output determines the checked state of the checkbox |
|
|
|checked |The value of the field corresponding to the checkbox being checked |
|
|
|unchecked |The value of the field corresponding to the checkbox being unchecked |
|
|
|default |The default value to use if the field is not defined |
|
|
|class |The class that will be assigned to the label element <$macrocall $name=".tip" _="""<<.from-version "5.2.3">> `tc-checkbox` is always applied by default, as well as `tc-checkbox-checked` when checked"""/> |
|
|
|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) |
|
|
|uncheckactions |<<.from-version "5.1.16">> A string containing ActionWidgets to be triggered when the checkbox is unchecked |
|
|
|checkactions |<<.from-version "5.1.20">> A string containing ActionWidgets to be triggered when the checkbox is checked |
|
|
|disabled|<<.from-version "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:
|
|
|
|
<<wikitext-example-without-html """<$checkbox tag="done"> Is it done?</$checkbox>""">>
|
|
|
|
!! 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.
|
|
|
|
<<wikitext-example-without-html """<$checkbox field="status" checked="open" unchecked="closed" default="closed"> Is it open?</$checkbox><br />''status:'' {{!!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.
|
|
|
|
<<wikitext-example-without-html """<$checkbox listField="colors" checked="green" unchecked="red" default="green"> Is it green?</$checkbox><br />''colors:'' {{!!colors}}""">>
|
|
|
|
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|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.
|
|
|
|
<$macrocall $name="wikitext-example-without-html" src="""<$checkbox tiddler="ExampleData" index=<<currentTiddler>> checked="selected" unchecked="" default=""> Selected?</$checkbox>"""/>
|
|
|
|
!! Index List Mode
|
|
|
|
Using the checkbox widget in index list mode requires the ''listIndex'' attribute to specify the the index of a [[DataTiddler|DataTiddlers]] 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.
|
|
|
|
<$macrocall $name="wikitext-example-without-html" src="""
|
|
<$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>
|
|
"""/>
|
|
|
|
!! 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.
|
|
|
|
<<wikitext-example-without-html """\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}}
|
|
""">>
|