mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-11-23 18:17:20 +00:00
Restructure and optimize CheckboxWidget docs (#7362)
* Restructure and optimize `CheckboxWidget` docs * Minor improvements * Use new tab macros and some reformatting * Fix bug in widget-attr-link tooltip * Minor layout tweaks * First try at a Widget Documentation Style Guide * Add new tabs-related macros to overview * Update CSS, add tm-scroll and rename macros * Avoid RSoE with tm-scroll, improve CSS for tab-links * Handle doc-tab-links within tab tiddlers better * Reflect macro name changes in their docs * Update Widget Doc Style Guide
This commit is contained in:
yaisog
GitHub
parent
f7c3ac4c54
commit
bfcb386343
@ -1,5 +1,5 @@
|
||||
created: 20150110182600000
|
||||
modified: 20211206080809651
|
||||
modified: 20230325161424684
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
title: Documentation Macros
|
||||
type: text/vnd.tiddlywiki
|
||||
@ -58,6 +58,13 @@ The following macros are used throughout ~TiddlyWiki's documentation. Their name
|
||||
|.wlink |a link to a widget |<<.wlink ButtonWidget>> |
|
||||
|.wlink2 |a link to a widget, with specified text |<<.wlink2 foo ButtonWidget>> |
|
||||
|
||||
!Tabs
|
||||
|!Macro |!Used for |!Example |
|
||||
|.doc-tabs |showing a tab set in a documentation tiddler | -- |
|
||||
|.doc-tab-link |button to activate a tab | -- |
|
||||
|.widget-attr-link |button with a widget attribute name to activate a tab | -- |
|
||||
|
||||
|
||||
!User interface
|
||||
|
||||
|!Macro |!Used for |!Example |
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
created: 20141226192500000
|
||||
modified: 20150117152552000
|
||||
title: Reference Tiddlers
|
||||
modified: 20230318160831470
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
title: Reference Tiddlers
|
||||
|
||||
<<.def "Reference tiddlers">> offer raw information in a comprehensive interlinked way. The reader is likely to be an intermediate or expert user.
|
||||
|
||||
@ -13,6 +13,7 @@ There are several subcategories:
|
||||
;User manual
|
||||
* Presenting technical details of ~WikiText features
|
||||
* Subcategorised: messages, operators, widgets, etc
|
||||
** Widget documentation should follow the [[Widget Documentation Style Guide]]
|
||||
|
||||
;Developer manual
|
||||
* Presenting technical details of ~TiddlyWiki's internal architecture
|
||||
|
||||
@ -0,0 +1,37 @@
|
||||
created: 20230318160840043
|
||||
modified: 20230325162525198
|
||||
tags: [[Reference Tiddlers]]
|
||||
title: Widget Documentation Style Guide
|
||||
|
||||
Widget documentation generally consists of
|
||||
|
||||
* an introductory summary of the widget's function
|
||||
* an overview of attributes and how the widget content is handled
|
||||
* more detailed attribute explanation when required
|
||||
* examples
|
||||
|
||||
The //Content and Attributes// section should describe how the content of the widget is used, followed by a table of the possible attributes, each with a short description of a single sentence. The attribute names in the table and elsewhere in the tiddler should be rendered with the <<.var .attr>> macro. The <<.var .from-version>> macro should be used as first item in the description to designate the version at which a parameter became available.
|
||||
|
||||
A subsection should be used for parameters that need an //extended description//, possibly with separate examples. When there are more than 2 such subsection necessary, the subsections should be split into their own tiddlers, and the <<.var .doc-tabs>> macro should be used to transclude them into the widget documentation tiddler as tabs.
|
||||
|
||||
* The <<.var .doc-tabs>> macro is used without parameters
|
||||
* The <<.var .doc-tabs>> macro must not be used more than once within a single documentation tiddler
|
||||
* The tiddlers to be included in the tab group should be tagged with the respective widget documentation tiddler and have a <<.field description>> field set to <<.value tab>>
|
||||
* The <<.field caption>> contains the tab button text. It should be as short as possible. For the attribute name, the <<.var .attr>> macro should be used in the <<.field caption>>
|
||||
* The tab tiddlers should start with a level-2-heading that links to itself, so that they may be opened from within the tabs
|
||||
* They can contain examples if these are specific to the topic of the subsection
|
||||
|
||||
In the attribute table, the <<.var .widget-attr-link>> macro can be used to turn attributes into a button that activates the respective tab. The <<.var .widget-attr-link>> macro is used like this
|
||||
|
||||
```
|
||||
<<.widget-attr-link text:<display text> target:<title of corresponding tiddler> >>
|
||||
```
|
||||
|
||||
Elsewhere, the <<.var .doc-tab-link>> macro can be used to activate the respective tab
|
||||
|
||||
```
|
||||
<<.doc-tab-link text:<display text> target:<title of corresponding tiddler> tooltip:<tooltip to show when hovering over the button> class:<additional classes> >>
|
||||
```
|
||||
The parameters <<.param tooltip>> and <<.param class>> are optional.
|
||||
|
||||
Both link macros scroll to the tab group additionally to setting the selected tab. They can also be used within the tab contents tiddlers themselves. If a tab tiddler is opened outside the tab group, <<.var doc-tab-link>> will open the tiddler containing the tab group if it is not yet open, and scroll to its tab group if it is.
|
||||
@ -1,5 +1,5 @@
|
||||
created: 20150117152607000
|
||||
modified: 20220714133424023
|
||||
modified: 20230325141733992
|
||||
tags: $:/tags/Macro
|
||||
title: $:/editions/tw5.com/doc-macros
|
||||
type: text/vnd.tiddlywiki
|
||||
@ -61,6 +61,37 @@ type: text/vnd.tiddlywiki
|
||||
\define .toc-tab() <<.tab "TableOfContents">>
|
||||
\define .example-tab(_) <span class="doc-tab">$_$</span>
|
||||
|
||||
\define .doc-tabs()
|
||||
<$macrocall $name="tabs"
|
||||
tabsList="[tag<currentTiddler>description[tab]]"
|
||||
default={{{ [tag<currentTiddler>first[]] }}}
|
||||
explicitState={{{ [<currentTiddler>addprefix[$:/state/tab/]] }}}
|
||||
class={{{ [[doc-tabs]] [<currentTiddler>encodeuricomponent[]escapecss[]addprefix[doc-tabs-]] +[join[ ]] }}} />
|
||||
\end
|
||||
\define .doc-tab-link(text, target, tooltip:"", class:"")
|
||||
<!-- figure out where the addressed doc-tabs are -->
|
||||
<$tiddler tiddler={{{ [<currentTiddler>search:text[.doc-tabs]] :else[<currentTiddler>tags[]search:text[.doc-tabs]first[]] :else[<currentTiddler>] }}} >
|
||||
<$button class={{{ [[tc-btn-invisible tc-tiddlylink]] [<__class__>] +[join[ ]] }}}
|
||||
set={{{ [<currentTiddler>addprefix[$:/state/tab/]] }}}
|
||||
setTo=<<__target__>>
|
||||
tooltip=<<__tooltip__>>>
|
||||
<<__text__>>
|
||||
<!-- if tiddler with tabs is open, scroll to tabs, otherwise open that tiddler (relevant from within tab subtiddlers) -->
|
||||
<$list filter="[[$:/StoryList]contains<currentTiddler>]" variable="ignore" emptyMessage="<$action-navigate />">
|
||||
<$action-sendmessage $message="tm-scroll" selector={{{ [<currentTiddler>encodeuricomponent[]addprefix[.doc-tabs-]] }}} />
|
||||
</$list>
|
||||
<$action-sendmessage $message="tm-scroll" selector={{{ [<currentTiddler>encodeuricomponent[]escapecss[]addprefix[.doc-tabs-]] }}} />
|
||||
</$button>
|
||||
</$tiddler>
|
||||
\end
|
||||
\define .widget-attr-link(text, target)
|
||||
<$macrocall $name=".doc-tab-link"
|
||||
text={{{ [[<code class="doc-attr">]] [<__text__>] [[</code>]] +[join[]] }}}
|
||||
class="doc-tab-link"
|
||||
target=<<__target__>>
|
||||
tooltip={{{ [[Show more information about the ']] [<__text__>] [[' attribute]] +[join[]] }}} />
|
||||
\end
|
||||
|
||||
\define .button(_) <span class="doc-button">{{$:/core/ui/Buttons/$_$!!caption}}</span>
|
||||
|
||||
\define .icon(_) <span class="doc-icon">{{$_$}}</span>
|
||||
@ -181,4 +212,4 @@ $credit$
|
||||
</ol>
|
||||
\end
|
||||
|
||||
<pre><$view field="text"/></pre>
|
||||
<pre><$view field="text"/></pre>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
created: 20150117152612000
|
||||
modified: 20220617125128201
|
||||
modified: 20230325101137075
|
||||
tags: $:/tags/Stylesheet
|
||||
title: $:/editions/tw5.com/doc-styles
|
||||
type: text/vnd.tiddlywiki
|
||||
@ -285,4 +285,14 @@ ol.doc-github-contributors li {
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
}
|
||||
|
||||
.doc-tabs.tc-tab-buttons button {
|
||||
font-size: 1rem;
|
||||
padding: 0.5em;
|
||||
}
|
||||
.doc-tabs button .doc-attr {
|
||||
background-color: unset;
|
||||
color: #666;
|
||||
}
|
||||
.doc-tab-link .doc-attr {
|
||||
color: unset;
|
||||
}
|
||||
@ -0,0 +1,16 @@
|
||||
caption: <<.attr field>>
|
||||
created: 20230314171223911
|
||||
description: tab
|
||||
modified: 20230317161110431
|
||||
tags: CheckboxWidget
|
||||
title: CheckboxWidget (field Mode)
|
||||
|
||||
!!<<.link "<<.attr field>> Mode" "CheckboxWidget (field Mode)">>
|
||||
|
||||
Using the checkbox widget in field mode requires the <<.attr field>> attribute to specify the name of the field. The <<.attr checked>> and <<.attr unchecked>> attributes specify the values to be assigned to the field to correspond to its checked and unchecked states respectively. The <<.attr default>> attribute is used as a fallback value if the field is missing or contains a value that does not correspond to the value of the <<.attr checked>> or <<.attr unchecked>> attributes.
|
||||
|
||||
This example creates a checkbox that is checked if the field <<.field status>> is equal to <<.value open>> and unchecked if the field is equal to <<.value closed>>. If the field value is undefined then it defaults to <<.value closed>>.
|
||||
|
||||
<<wikitext-example-without-html """<$checkbox field="status" checked="open" unchecked="closed" default="closed"> Is it open?</$checkbox>
|
||||
|
||||
''status:'' {{!!status}}""">>
|
||||
@ -0,0 +1,23 @@
|
||||
caption: <<.attr filter>>
|
||||
created: 20230314174505003
|
||||
description: tab
|
||||
modified: 20230325101447667
|
||||
tags: CheckboxWidget
|
||||
title: CheckboxWidget (filter Mode)
|
||||
|
||||
!!<<.link "<<.attr filter>> Mode" "CheckboxWidget (filter Mode)">>
|
||||
|
||||
Using the checkbox widget in filter mode requires the <<.attr 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 <<.attr actions>> attribute (or the <<.attr checkactions>> and <<.attr uncheckactions>> attributes) 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 and the filter has updated.
|
||||
|
||||
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 <<.attr checked>> or <<.attr 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 <<.value checked>>.
|
||||
|
||||
This example creates the same checkbox as in the <<.doc-tab-link "listField mode example" "CheckboxWidget (listField Mode)">>, selecting between <<.value red>> and <<.value green>> in the <<.field 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>
|
||||
|
||||
''colors:'' {{!!colors}}
|
||||
""">>
|
||||
@ -0,0 +1,31 @@
|
||||
caption: <<.attr indeterminate>>
|
||||
created: 20230315173145042
|
||||
description: tab
|
||||
modified: 20230317160908743
|
||||
tags: CheckboxWidget
|
||||
title: CheckboxWidget (indeterminate)
|
||||
|
||||
!!<<.link "<<.attr indeterminate>> Checkboxes" "CheckboxWidget (indeterminate)">>
|
||||
|
||||
If both the <<.attr checked>> and <<.attr 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 <<.attr indeterminate>> attribute is set to <<.value yes>> (default is <<.value 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 <<.attr 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 <<.field fruits>> and <<.field vegetables>> fields on this tiddler and see what happens to the example when you do.
|
||||
|
||||
<<wikitext-example-without-html """\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>""">>
|
||||
@ -0,0 +1,16 @@
|
||||
caption: <<.attr index>>
|
||||
created: 20230314171351122
|
||||
description: tab
|
||||
modified: 20230317160939333
|
||||
tags: CheckboxWidget
|
||||
title: CheckboxWidget (index Mode)
|
||||
|
||||
!!<<.link "<<.attr index>> Mode" "CheckboxWidget (index Mode)">>
|
||||
|
||||
To use the checkbox widget in index mode set the <<.attr index>> attribute to a property of a [[DataTiddler|DataTiddlers]]. The <<.attr checked>> and <<.attr unchecked>> attributes specify the values to be assigned to the property and correspond to its checked and unchecked states respectively. The <<.attr default>> attribute is used as a fallback value if the property is undefined.
|
||||
|
||||
<<.warning "Make sure to set <<.attr tiddler>> correctly, because non-[[DataTiddlers]] will be overwritten without warning">>
|
||||
|
||||
The example below creates a checkbox that is checked if the property in the tiddler [[ExampleData]] by the name of the current tiddler is equal to <<.value selected>> and unchecked if the property is an empty string. If the property is undefined then it defaults to an empty string, meaning the checkbox will be unchecked if the property is missing.
|
||||
|
||||
<$macrocall $name="wikitext-example-without-html" src="""<$checkbox tiddler="ExampleData" index=<<currentTiddler>> checked="selected" unchecked="" default=""> Selected?</$checkbox>"""/>
|
||||
@ -0,0 +1,26 @@
|
||||
caption: <<.attr listField>>
|
||||
created: 20230314171331190
|
||||
description: tab
|
||||
modified: 20230317160948525
|
||||
tags: CheckboxWidget
|
||||
title: CheckboxWidget (listField Mode)
|
||||
|
||||
!!<<.link "<<.attr listField>> Mode" "CheckboxWidget (listField Mode)">>
|
||||
|
||||
Using the checkbox widget in list mode requires the <<.attr listField>> attribute to specify the name of a field containing a list. The <<.attr checked>> attribute specifies the value that should be present or absent in the list when the checkbox is checked or unchecked respectively. If <<.attr checked>> is absent (or empty) but <<.attr unchecked>> is present, then the logic will be inverted: the checkbox will be checked when the <<.attr unchecked>> value is missing from the list, and unchecked when the <<.attr unchecked>> value is found in the list. If both <<.attr checked>> and <<.attr unchecked>> are present, the checkbox will work like a toggle, replacing the <<.attr checked>> value with the <<.attr unchecked>> value and vice-versa. Finally, if neither <<.attr checked>> nor <<.attr 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 want to specify <<.attr checked>> or <<.attr unchecked>> or both.)
|
||||
|
||||
The <<.attr default>> attribute is used as a fallback for the checkbox state if the field is not defined.
|
||||
|
||||
The following table summarizes the possible combinations:
|
||||
|
||||
| !defined attributes| !<$checkbox tag="void" disabled="yes"/> | !<$checkbox field="tag" checked="void" default="void" disabled="yes" /> | !<$checkbox listField="tag" checked="void" unchecked="invalid" indeterminate="yes" disabled="yes" /> |
|
||||
| neither| field missing or list empty<br/>no <<.attr default>> defined | field has any value | -- |
|
||||
| <<.attr checked>>=<<.value item1>>| <<.value item1>> removed from list | <<.value item1>> added to list | -- |
|
||||
| <<.attr unchecked>>=<<.value item2>>| <<.value item2>> added to list | <<.value item2>> removed from list | -- |
|
||||
| both| <<.value item1>> removed from list<br/><<.value item2>> added to list | <<.value item1>> added to list<br/><<.value item2>> removed from list | <<.value item1>> not in list<br/><<.value item2>> not in list<br/>no <<.attr default>> defined |
|
||||
|
||||
This example creates a checkbox that is checked if the list field named <<.field colors>> contains <<.value green>> and unchecked if the field contains <<.value red>>. If the field is undefined, or if neither <<.value green>> nor <<.value red>> appears in the field, then it defaults to <<.value green>>, meaning that the checkbox will be checked.
|
||||
|
||||
<<wikitext-example-without-html """<$checkbox listField="colors" checked="green" unchecked="red" default="green"> Is "green" in colors?</$checkbox><br />''colors:'' {{!!colors}}""">>
|
||||
|
||||
Try editing the <<.field colors>> field of this tiddler to see how the example changes.
|
||||
@ -0,0 +1,32 @@
|
||||
caption: <<.attr listIndex>>
|
||||
created: 20230314174442174
|
||||
description: tab
|
||||
modified: 20230317160929003
|
||||
tags: CheckboxWidget
|
||||
title: CheckboxWidget (listIndex Mode)
|
||||
|
||||
!!<<.link "<<.attr listIndex>> Mode" "CheckboxWidget (listIndex Mode)">>
|
||||
|
||||
Using the checkbox widget in index list mode requires the <<.attr listIndex>> attribute to specify the the property of a [[DataTiddler|DataTiddlers]]. This property contains a list. The <<.attr checked>> attribute specifies the value that should be present or absent in the list when the checkbox is checked or unchecked respectively. If <<.attr checked>> is absent (or empty) but <<.attr unchecked>> is present, then the logic will be inverted: the checkbox will be checked when the <<.attr unchecked>> value is missing from the list, and unchecked when the <<.attr unchecked>> value is found in the list. If both <<.attr checked>> and <<.attr unchecked>> are present, the checkbox will work like a toggle, replacing the <<.attr checked>> value with the <<.attr unchecked>> value and vice-versa. Finally, if neither <<.attr checked>> nor <<.attr 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 want to specify <<.attr checked>> or <<.attr unchecked>> or both.)
|
||||
|
||||
The <<.attr default>> attribute is used as a fallback for the checkbox state if the property is undefined.
|
||||
|
||||
The following table summarizes the possible combinations:
|
||||
|
||||
| !defined attributes| !<$checkbox tag="void" disabled="yes"/> | !<$checkbox field="tag" checked="void" default="void" disabled="yes" /> | !<$checkbox listField="tag" checked="void" unchecked="invalid" indeterminate="yes" disabled="yes" /> |
|
||||
| neither| property missing or list empty<br/>no <<.attr default>> defined | property has any value | -- |
|
||||
| <<.attr checked>>=<<.value item1>>| <<.value item1>> removed from list | <<.value item1>> added to list | -- |
|
||||
| <<.attr unchecked>>=<<.value item2>>| <<.value item2>> added to list | <<.value item2>> removed from list | -- |
|
||||
| both| <<.value item1>> removed from list<br/><<.value item2>> added to list | <<.value item1>> added to list<br/><<.value item2>> removed from list | <<.value item1>> not in list<br/><<.value item2>> not in list<br/>no <<.attr default>> defined |
|
||||
|
||||
<<.warning "Make sure to set <<.attr tiddler>> correctly, because non-[[DataTiddlers]] will be overwritten without warning">>
|
||||
|
||||
The example below creates three checkboxes that each control a different value in a property 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: <$text text={{{ [[ExampleData]getindex<indexName>] }}} />
|
||||
</$set>
|
||||
"""/>
|
||||
@ -0,0 +1,18 @@
|
||||
caption: <<.attr tag>>
|
||||
created: 20230314171205017
|
||||
description: tab
|
||||
modified: 20230317161122617
|
||||
tags: CheckboxWidget
|
||||
title: CheckboxWidget (tag Mode)
|
||||
|
||||
!!<<.link "<<.attr tag>> Mode" "CheckboxWidget (tag Mode)">>
|
||||
|
||||
Using the checkbox widget in tag mode requires the <<.attr tag>> attribute to specify the name of the tag. The checkbox will be checked if the tiddler specified in the <<.attr tiddler>> attribute has the specified tag and unchecked if it does not.
|
||||
|
||||
This example creates a checkbox that flips the <<.tag done>> tag on the current tiddler:
|
||||
|
||||
<<wikitext-example-without-html """<$checkbox tag="done"> Is it done?</$checkbox>""">>
|
||||
|
||||
When the attribute <<.attr invertTag>> is set to <<.value yes>>, the checkbox will be checked if the tiddler does <<.em not>> have the specified tag and unchecked if it does.
|
||||
|
||||
<<wikitext-example-without-html """<$checkbox tag="done" invertTag="yes"> Is it not done?</$checkbox>""">>
|
||||
@ -1,12 +1,13 @@
|
||||
caption: checkbox
|
||||
created: 20131024141900000
|
||||
modified: 20220402023600000
|
||||
tags: Widgets TriggeringWidgets
|
||||
colors: red orange yellow blue
|
||||
created: 20131024141900000
|
||||
fruits: bananas oranges grapes
|
||||
vegetables: carrots potatoes
|
||||
list: [[CheckboxWidget (tag Mode)]] [[CheckboxWidget (field Mode)]] [[CheckboxWidget (listField Mode)]] [[CheckboxWidget (index Mode)]] [[CheckboxWidget (listIndex Mode)]] [[CheckboxWidget (filter Mode)]] [[CheckboxWidget (indeterminate)]]
|
||||
modified: 20230316192632667
|
||||
tags: Widgets TriggeringWidgets
|
||||
title: CheckboxWidget
|
||||
type: text/vnd.tiddlywiki
|
||||
vegetables: carrots potatoes
|
||||
|
||||
! Introduction
|
||||
|
||||
@ -20,111 +21,22 @@ The checkbox widget displays an HTML `<input type="checkbox">` element that is d
|
||||
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 |
|
||||
|indeterminate |Whether ambiguous values can produce indeterminate checkboxes (see below) |
|
||||
|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"|
|
||||
|<<.attr tiddler>> |Title of the tiddler to manipulate (defaults to the [[Current Tiddler]]) |
|
||||
|<<.widget-attr-link tag "CheckboxWidget (tag Mode)">> |The name of the [[tag|Tagging]] to which the checkbox is bound |
|
||||
|<<.attr invertTag>> |When set to <<.value yes>>, flips the tag binding logic so that the absence of the tag causes the checkbox to be checked |
|
||||
|<<.widget-attr-link field "CheckboxWidget (field Mode)">> |The name of the field to which the checkbox is bound |
|
||||
|<<.widget-attr-link listField "CheckboxWidget (listField Mode)">> |<<.from-version "5.2.3">> The name of the field that contains the list to which the checkbox is bound |
|
||||
|<<.widget-attr-link index "CheckboxWidget (index Mode)">> |<<.from-version "5.1.14">> The property of the [[DataTiddler|DataTiddlers]] to which the checkbox is bound|
|
||||
|<<.widget-attr-link listIndex "CheckboxWidget (listIndex Mode)">> |<<.from-version "5.2.3">> Like <<.attr index>>, but treats the value as a list the same way that <<.attr listField>> does |
|
||||
|<<.widget-attr-link filter "CheckboxWidget (filter Mode)">> |<<.from-version "5.2.3">> A filter whose output determines the checked state of the checkbox |
|
||||
|<<.attr checked>> |The value of the field corresponding to the checkbox being checked |
|
||||
|<<.attr unchecked>> |The value of the field corresponding to the checkbox being unchecked |
|
||||
|<<.attr default>> |The default value to use if the field is not defined |
|
||||
|<<.widget-attr-link indeterminate "CheckboxWidget (indeterminate)">> |Whether ambiguous values can produce indeterminate checkboxes (see below) |
|
||||
|<<.attr 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"""/> |
|
||||
|<<.attr 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) |
|
||||
|<<.attr uncheckactions>> |<<.from-version "5.1.16">> A string containing ActionWidgets to be triggered when the checkbox is unchecked |
|
||||
|<<.attr checkactions>> |<<.from-version "5.1.20">> A string containing ActionWidgets to be triggered when the checkbox is checked |
|
||||
|<<.attr disabled>> |<<.from-version "5.1.23">> Optionally disables the checkbox if set to <<.value yes>> (defaults to <<.value 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}}
|
||||
""">>
|
||||
|
||||
!! 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 <<.field fruits>> and <<.field vegetables>> fields on this tiddler and see what happens to the example when you do.
|
||||
|
||||
<<wikitext-example-without-html """\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>""">>
|
||||
<<.doc-tabs>>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user