1
0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2024-12-24 17:10:29 +00:00

Document the tv-* variables

This commit is contained in:
Astrid Elocson 2015-02-28 14:38:00 +00:00
parent b30d43215c
commit f73891c083
32 changed files with 373 additions and 64 deletions

View File

@ -1,5 +1,5 @@
created: 20140211171341271
modified: 20150221220245000
modified: 20150228114909000
tags: Concepts Reference
title: Macros
type: text/vnd.tiddlywiki
@ -22,7 +22,7 @@ The <<.mlink dumpvariables>> macro lists all variables (including macros) that a
An <<.wlink ImportVariablesWidget>> widget can be used to copy macro definitions to another branch of the [[widget tree|Widgets]]. ~TiddlyWiki uses this technique internally to implement global macros -- namely any macros defined in tiddlers with the <<.tag $:/tags/Macro>> tag.
For maximum flexibility, macros can also be [[written as JavaScript modules|http://tiddlywiki.com/dev/index.html#JavaScript%20Macros]].
For maximum flexibility, macros can also be <<.js-macro-link "written as JavaScript modules">>.
A similar effect to a parameterised macro call can be produced by setting [[variables|Variables]] around a [[transclusion|Transclusion]].

View File

@ -0,0 +1,11 @@
created: 20150228133106000
modified: 20150228134018000
tags: Definitions
title: Document Object Model
type: text/vnd.tiddlywiki
The <<.dlink-ex DOM "http://en.wikipedia.org/wiki/Document_Object_Model">> of a web page is a tree-shaped model of its content, maintained internally by the web browser as the user interacts with that content. Each point in the tree is called a <<.def node>>.
When ~TiddlyWiki is running in a web browser, its [[widgets|Widgets]] are rendered into DOM nodes for display.
When ~TiddlyWiki is running on [[Node.js|TiddlyWiki on Node.js]], it uses a fake DOM to simulate the behaviour of a browser.

View File

@ -0,0 +1,11 @@
created: 20150228132723000
modified: 20150228133925000
tags: Definitions
title: HyperText Markup Language
type: text/vnd.tiddlywiki
<<.dlink-ex HTML "http://en.wikipedia.org/wiki/HTML">> is a standard plain-text format used for defining the content of a web page.
It consists of a tree of elements expressed using a system of special <<.def tags>> enclosed in angle brackets.
Almost the whole of HTML can be used unchanged in the WikiText of a tiddler.

View File

@ -0,0 +1,11 @@
created: 20150228131248000
modified: 20150228131522000
tags: Definitions
title: Percent Encoding
type: text/vnd.tiddlywiki
<<.dlink-ex "Percent encoding" "http://en.wikipedia.org/wiki/Percent-encoding">> is a notation that allows otherwise invalid characters to be included in a [[URI]].
Such characters are represented as a percent sign `%` followed by two additional characters.
For example, a space is represented as `%20` and an actual percent sign is represented as `%25`.

View File

@ -0,0 +1,7 @@
created: 20150228113450000
modified: 20150228113654000
tags: Definitions
title: URI
type: text/vnd.tiddlywiki
A <<.dlink-ex "URI" "http://en.wikipedia.org/wiki/Uniform_resource_identifier">> (also often known as a <<.def URL>>) is a string of characters used to specify the location of a resource such as a web page.

View File

@ -1,5 +1,5 @@
created: 20140410101941871
modified: 20150226162742000
modified: 20150228104558000
tags: Learning Filters
title: Introduction to filter notation
type: text/vnd.tiddlywiki
@ -10,62 +10,43 @@ type: text/vnd.tiddlywiki
The simplest case is where you already know exactly which tiddlers you want. Type each title in double square brackets, with a space between each one and the next:
```
[[Recipe book]] [[ScrambledEggs]] [[Mom's apple pie]]
```
> `[[Recipe book]] [[ScrambledEggs]] [[Mom's apple pie]]`
You can omit the square brackets when a title doesn't contain any spaces:
```
[[Recipe book]] ScrambledEggs [[Mom's apple pie]]
```
> `[[Recipe book]] ScrambledEggs [[Mom's apple pie]]`
The double square brackets are actually a shorthand for this:
```
[title[ScrambledEggs]]
```
> `[title[ScrambledEggs]]`
... which gives us the <<.def "general model">> for any filter:
```
[operator[parameter]]
```
> `[operator[parameter]]`
For instance, here's how to select all the tiddlers that have been tagged <<.tag Recipe>>:
```
[tag[Recipe]]
```
> `[tag[Recipe]]`
We can reverse the meaning by adding an exclamation mark `!` just before the operator. For example, we can select any tiddlers that do <<.em not>> have the <<.tag Recipe>> tag:
```
[!tag[Recipe]]
```
> `[!tag[Recipe]]`
Tiddlers can be filtered by other fields than just title and tags:
```
[field:serving[4]]
```
> `[field:serving[4]]`
That example will select any tiddlers that have <<.value 4>> in their <<.field serving>> field.
As the word "serving" isn't a standard filter operator (and isn't likely to become one), you can safely omit the `field:` prefix:
```
[serving[4]]
```
> `[serving[4]]`
!Combinations
The filters we've looked at so far have involved just one step each. But you can <<.def run>> several steps together like this:
```
[tag[Vegetarian]!tag[soup]serving[4]]
```
> `[tag[Vegetarian]!tag[soup]serving[4]]`
Notice how the entire run is contained in a single pair of square brackets.
@ -73,29 +54,21 @@ A tiddler has to match <<.em all>> of the steps in a run. So the example above r
A sequence of separate runs will select the tiddlers that match <<.em any>> of the runs. We can use this to find recipes that serve either 3, 4 or 5 people:
```
[serving[3]] [serving[4]] [serving[5]]
```
> `[serving[3]] [serving[4]] [serving[5]]`
If we want to ignore vegetarian recipes that serve 4, we can say this:
```
[serving[3]] [serving[4]!tag[Vegetarian]] [serving[5]]
```
> `[serving[3]] [serving[4]!tag[Vegetarian]] [serving[5]]`
By default, each run considers every tiddler in the wiki. But we can use a `+` sign to force a run to consider only the tiddlers that were selected by the preceding runs:
```
[serving[3]] [serving[4]] [serving[5]] +[tag[Vegetarian]] +[sort[title]]
```
> `[serving[3]] [serving[4]] [serving[5]] +[tag[Vegetarian]] +[sort[title]]`
This selects recipes for 3, 4 or 5 people, then filters <<.em those>> to remove the vegetarian ones, and finally sorts any that are left into alphabetical order of title.
In a similar way, we can use a `-` sign to <<.em remove>> a run's tiddlers from the result so far. Here we select all vegetarian recipes apart from two:
```
[tag[Vegetarian]] -[title[ScrambledEggs]] -BeansOnToast
```
> `[tag[Vegetarian]] -[title[ScrambledEggs]] -BeansOnToast`
!Special parameters
@ -103,14 +76,10 @@ The parameter of each step we've seen so far has been in square brackets, meanin
<<.def "Curly brackets">> `{}` mean that the parameter is a TextReference, and that its value is to be looked up in a specified tiddler. For example, if we have a tiddler called <<.tid Preference>> whose text happens to be the word <<.value Vegetarian>>, we can say
```
[tag{Preference}]
```
> `[tag{Preference}]`
as an alternative to `[tag[Vegetarian]]`. This allows the preference to change over time.
<<.def "Angle brackets">> `<>` mean that the parameter is the name of a [[variable|Variables]] whose value is to be used instead. Here we use the built-in <<.vlink currentTiddler>> variable in a filter that selects any tiddlers whose text contains the title of the current one:
```
[search<currentTiddler>]
```
> `[search<currentTiddler>]`

View File

@ -0,0 +1,6 @@
created: 20150228123855000
modified: 20150228123921000
title: $:/editions/tw5.com/macro-examples/tv-get-export-image-link
type: text/vnd.tiddlywiki
\define tv-get-export-image-link(src) http://www.tiddlywiki.com/$src$

View File

@ -0,0 +1,8 @@
created: 20150228120252000
modified: 20150228120554000
title: $:/editions/tw5.com/macro-examples/tv-wikilink-tooltip
type: text/vnd.tiddlywiki
\define tv-wikilink-tooltip()
<$transclude field="tooltip">(<$transclude field="caption"/>)</$transclude>
\end

View File

@ -1,5 +1,5 @@
created: 20140716084658099
modified: 20140716195055502
modified: 20150228143618000
tags: Messages navigator-message
title: WidgetMessage: tm-import-tiddlers
type: text/vnd.tiddlywiki
@ -14,7 +14,4 @@ The import tiddlers message is usually generated with the DropzoneWidget or the
! Configuration Variables
The variable `tv-auto-open-on-import` controls whether the `tm-import-tiddlers` message automatically triggers the display of the pending import tiddler [[$:/Import]]:
* ''no'': The pending import tiddler is not opened in the story
* ''yes'': The pending import tiddler is opened in th story. This is the default
* <<.vlink tv-auto-open-on-import>>

View File

@ -1,5 +1,5 @@
created: 20150110182600000
modified: 20150226161700000
modified: 20150228082845000
title: Documentation Macros
tags: [[Improving TiddlyWiki Documentation]]
@ -18,7 +18,7 @@ The following macros are used throughout ~TiddlyWiki's documentation. Their name
|!Macro |!Used for |!Example |
|^.tip |^hints and tips |<<.tip "Turn your screen on, otherwise<br>you won't be able to see much.">> |
|^.warning |^warning advice |<<.warning "Make a backup of your file<br>before your upgrade.">> |
|^.warning |^warning advice |<<.warning "Make a backup of your file<br>before you upgrade.">> |
!Blocks
|!Macro |!Used for |

View File

@ -64,7 +64,6 @@ tags: $:/tags/Macro
\define .tip(_) <div class="doc-icon-block"><div class="doc-block-icon">{{$:/core/images/tip}}</div> $_$</div>
\define .warning(_) <div class="doc-icon-block"><div class="doc-block-icon">{{$:/core/images/warning}}</div> $_$</div>
\end
\define .state-prefix() $:/state/editions/tw5.com/

View File

@ -1,11 +1,9 @@
created: 20150117152607000
modified: 20150221151136000
modified: 20150228114306000
title: $:/editions/tw5.com/operator-macros
tags: $:/tags/Macro
\define .operator-examples(op,text:"Examples") <$link to="$op$ Operator (Examples)">$text$</$link>
\define .variable-examples(v,text:"Examples") <$link to="$v$ Variable (Examples)">$text$</$link>
\define .macro-examples(m,text:"Examples") <$link to="$m$ Macro (Examples)">$text$</$link>
\define .operator-example(n,eg,ie)
<div class="doc-example">

View File

@ -0,0 +1,18 @@
created: 20150228114241000
modified: 20150228141312000
title: $:/editions/tw5.com/variable-macros
tags: $:/tags/Macro
\define .variable-examples(v,text:"Examples") <$link to="$v$ Variable (Examples)">$text$</$link>
\define .macro-examples(m,text:"Examples") <$link to="$m$ Macro (Examples)">$text$</$link>
\define .js-macro-link(_) [[$_$|http://tiddlywiki.com/dev/index.html#JavaScript%20Macros]]
\define .this-is-static-link-variable() <<.tip "This variable has no useful effect when ~TiddlyWiki is running in a browser, as the `href` attribute is ignored there -- links between tiddlers are performed by JavaScript instead. The variable comes into play when one is using the [[Node.js configuration|TiddlyWiki on Node.js]] to [[generate a static version|RenderTiddlersCommand]] of a wiki.">>
\define .this-is-toolbar-config-variable(configTiddler)
It can be set to <<.value yes>> or <<.value no>> prior to transcluding such a button.
The standard page template sets it to the value found in [[$configTiddler$]], with the result that this becomes the default for the whole page. The user can adjust this default by using a tickbox on the <<.controlpanel-tab Settings>> tab of the [[Control Panel|$:/ControlPanel]].
\end

View File

@ -1,8 +1,12 @@
created: 20150220161908000
modified: 20150221222104000
modified: 20150228134138000
title: Core Variables
type: text/vnd.tiddlywiki
The following [[variables|Variables]] are built into ~TiddlyWiki's core:
<<list-links "[tag[Core Variables]]">>
<<list-links "[tag[Core Variables]] -[tag[Configuration Variables]]">>
The core will also use various configuration variables and macros if you define them:
<<list-links "[tag[Configuration Variables]]">>

View File

@ -1,12 +1,12 @@
created: 20150221141507000
modified: 20150221144853000
modified: 20150228103440000
tags: [[transclusion Variable]] [[Variable Examples]]
title: transclusion Variable (Examples)
type: text/vnd.tiddlywiki
This example shows how to distinguish between the sidebar and other environments:
<$macrocall $name=".example" n="3"
<$macrocall $name=".example" n="1"
eg="""We are
<$list
filter="[<transclusion>prefix[{|$:/core/ui/PageTemplate/sidebar|||}]]"

View File

@ -0,0 +1,26 @@
created: 20150228135051000
modified: 20150228135737000
tags: [[tv-config-toolbar-class Variable]] [[Variable Examples]]
title: tv-config-toolbar-class Variable (Examples)
type: text/vnd.tiddlywiki
<style>
.green-background {
background-color: green;
fill: white;
}
</style>
<$macrocall $name=".example" n="1"
eg="""<$set name="tv-config-toolbar-class" value="tc-btn-invisible">
{{$:/core/ui/Buttons/new-tiddler}}
</$set>
"""/>
<$macrocall $name=".example" n="2"
eg="""<$set name="tv-config-toolbar-class" value="green-background">
{{$:/core/ui/Buttons/new-tiddler}}
</$set>
"""/>
The `green-background` [[CSS|Cascading Style Sheets]] class is declared in a stylesheet within this tiddler.

View File

@ -0,0 +1,19 @@
created: 20150228140420000
modified: 20150228141418000
tags: [[tv-config-toolbar-icons Variable]] [[Variable Examples]]
title: tv-config-toolbar-icons Variable (Examples)
type: text/vnd.tiddlywiki
<$macrocall $name=".example" n="1"
eg="""<$set name="tv-config-toolbar-icons" value="no">
<$set name="tv-config-toolbar-text" value="yes">
{{$:/core/ui/Buttons/new-tiddler}}
</$set>
</$set>
"""/>
<$macrocall $name=".example" n="2"
eg="""<$set name="tv-config-toolbar-icons" value="yes">
{{$:/core/ui/Buttons/new-tiddler}}
</$set>
"""/>

View File

@ -0,0 +1,17 @@
created: 20150228140420000
modified: 20150228140516000
tags: [[tv-config-toolbar-text Variable]] [[Variable Examples]]
title: tv-config-toolbar-text Variable (Examples)
type: text/vnd.tiddlywiki
<$macrocall $name=".example" n="1"
eg="""<$set name="tv-config-toolbar-text" value="no">
{{$:/core/ui/Buttons/new-tiddler}}
</$set>
"""/>
<$macrocall $name=".example" n="2"
eg="""<$set name="tv-config-toolbar-text" value="yes">
{{$:/core/ui/Buttons/new-tiddler}}
</$set>
"""/>

View File

@ -0,0 +1,11 @@
created: 20150228124038000
tags: [[tv-get-export-image-link Variable]] [[Variable Examples]]
title: tv-get-export-image-link Variable (Examples)
type: text/vnd.tiddlywiki
This example fetches [[the TiddlyWiki icon|http://www.tiddlywiki.com/favicon.ico]]:
<$importvariables filter="$:/editions/tw5.com/macro-examples/tv-get-export-image-link">
<$codeblock code={{$:/editions/tw5.com/macro-examples/tv-get-export-image-link}}/>
<$macrocall $name=".example" n="1" eg="""[img[favicon.ico]]"""/>
</$importvariables>

View File

@ -0,0 +1,14 @@
created: 20150228115959000
modified: 20150228120621000
tags: [[tv-wikilink-tooltip Variable]] [[Variable Examples]]
title: tv-wikilink-tooltip Variable (Examples)
type: text/vnd.tiddlywiki
This example shows a way of giving links a tooltip derived from the target tiddler's <<.field caption>> field:
<$importvariables filter="$:/editions/tw5.com/macro-examples/tv-wikilink-tooltip">
<$codeblock code={{$:/editions/tw5.com/macro-examples/tv-wikilink-tooltip}}/>
<$macrocall $name=".example" n="1" eg="""Here is a link to [[backlinks Operator]] with a custom tooltip."""/>
</$importvariables>
Here is [[a standard link|HelloThere]] for comparison.

View File

@ -0,0 +1,17 @@
created: 20150228103411000
modified: 20150228104438000
tags: [[tv-wikilinks Variable]] [[Variable Examples]]
title: tv-wikilinks Variable (Examples)
type: text/vnd.tiddlywiki
<$macrocall $name=".example" n="1"
eg="""HelloThere,
[[HelloThere]],
<$link to="HelloThere">is //this// a link?</$link>"""/>
<$macrocall $name=".example" n="2"
eg="""<$set name="tv-wikilinks" value="no">
HelloThere,
[[HelloThere]],
<$link to="HelloThere">is //this// a link?</$link>
</$set>"""/>

View File

@ -0,0 +1,10 @@
created: 20150228132024000
modified: 20150228133745000
title: namespace Variable
tags: Variables [[Core Variables]]
type: text/vnd.tiddlywiki
caption: namespace
The <<.def namespace>> [[variable|Variables]] is used internally by [[HTML|HyperText Markup Language]] widgets to keep track of the correct namespace for the [[DOM|Document Object Model]] elements they generate.
An `svg` or `math` element supplies a distinct namespace for itself and any child elements it contains.

View File

@ -0,0 +1,12 @@
created: 20150228120919000
modified: 20150228130407000
title: tv-auto-open-on-import Variable
tags: Variables [[Core Variables]] [[Configuration Variables]]
type: text/vnd.tiddlywiki
caption: tv-auto-open-on-import
The <<.def tv-auto-open-on-import>> [[variable|Variables]] controls whether the `tm-import-tiddlers` message causes the tiddler [[$:/Import]] (which lists the pending imports) to open in the story river.
By default, the tiddler is opened. But if this variable has the value <<.value no>>, it isn't.
An example of setting this variable to <<.value no>> can be found in the upgrade plugin within the [[TiddlyWiki Upgrade Wizard|http://www.tiddlywiki.com/upgrade.html]]. People can drag their wiki files onto the wizard without triggering the normal import display.

View File

@ -0,0 +1,14 @@
created: 20150228134732000
modified: 20150228135803000
title: tv-config-toolbar-class Variable
tags: Variables [[Core Variables]] [[Configuration Variables]]
type: text/vnd.tiddlywiki
caption: tv-config-toolbar-class
The <<.def tv-config-toolbar-class>> [[variable|Variables]] controls the value of the [[CSS|Cascading Style Sheets]] `class` attribute on the HTML element for a toolbar button.
It can be set prior to transcluding such a button.
In most environments, it defaults to <<.value tc-btn-invisible>>, which removes the button's background colour and border.
<<.variable-examples "tv-config-toolbar-class">>

View File

@ -0,0 +1,14 @@
created: 20150228135910000
modified: 20150228141357000
title: tv-config-toolbar-icons Variable
tags: Variables [[Core Variables]] [[Configuration Variables]]
type: text/vnd.tiddlywiki
caption: tv-config-toolbar-icons
The <<.def tv-config-toolbar-icons>> [[variable|Variables]] controls whether toolbar buttons display icons.
<<.this-is-toolbar-config-variable $:/config/Toolbar/Icons>>
<<.variable-examples "tv-config-toolbar-icons">>
See also <<.vlink tv-config-toolbar-text>>.

View File

@ -0,0 +1,14 @@
created: 20150228135910000
modified: 20150228141403000
title: tv-config-toolbar-text Variable
tags: Variables [[Core Variables]] [[Configuration Variables]]
type: text/vnd.tiddlywiki
caption: tv-config-toolbar-text
The <<.def tv-config-toolbar-text>> [[variable|Variables]] controls whether toolbar buttons display text.
<<.this-is-toolbar-config-variable $:/config/Toolbar/Text>>
<<.variable-examples "tv-config-toolbar-text">>
See also <<.vlink tv-config-toolbar-icons>>.

View File

@ -0,0 +1,17 @@
created: 20150228122257000
modified: 20150228130940000
title: tv-get-export-image-link Variable
tags: Variables [[Core Variables]] [[Configuration Variables]]
type: text/vnd.tiddlywiki
caption: tv-get-export-image-link
The <<.def tv-get-export-image-link>> [[variable|Variables]] controls the value of the `src` attribute on the HTML `img` element generated by the <<.wlink ImageWidget>> widget when the value of its `source` attribute is not the title of a tiddler.
The variable should be a [[macro|Macros]] with the following parameter:
;src
: The value of the `source` attribute -- equivalent to the image name specified in <$link to="Images in WikiText">the shorthand syntax</$link> `[img[source]]`
The ability to override image URIs in this way can be useful when one is using the [[Node.js configuration|TiddlyWiki on Node.js]] to export a static version of a wiki.
<<.variable-examples "tv-get-export-image-link">>

View File

@ -0,0 +1,17 @@
created: 20150228114004000
modified: 20150228130943000
title: tv-get-export-link Variable
tags: Variables [[Core Variables]] [[Configuration Variables]]
type: text/vnd.tiddlywiki
caption: tv-get-export-link
The <<.def tv-get-export-link>> [[variable|Variables]] controls the value of the `href` attribute on the HTML `a` element generated by the <<.wlink LinkWidget>> widget.
<<.this-is-static-link-variable>>
The variable should be a [[macro|Macros]] with the following parameter:
;to
: The title of the target tiddler of the link, with no escaping
See also <<.vlink tv-wikilink-template>>. If both that variable and this one exist, this one dominates.

View File

@ -0,0 +1,15 @@
created: 20150228130131000
modified: 20150228131730000
title: tv-get-export-path Variable
tags: Variables [[Core Variables]] [[Configuration Variables]]
type: text/vnd.tiddlywiki
caption: tv-get-export-path
The <<.def tv-get-export-path>> [[variable|Variables]] specifies the full pathname to which the <<.clink rendertiddlers RenderTiddlersCommand>> [[Node.js|TiddlyWiki on Node.js]] command writes each tiddler.
The variable should be implemented as a <<.js-macro-link "JavaScript macro">> with the following parameter:
;title
: The title of the tiddler
If no such macro exists, the tiddlers are written to files whose names are [[percent-encoded|Percent Encoding]], in the command's output folder.

View File

@ -0,0 +1,23 @@
created: 20150228105954000
modified: 20150228131300000
title: tv-wikilink-template Variable
tags: Variables [[Core Variables]] [[Configuration Variables]]
type: text/vnd.tiddlywiki
caption: tv-wikilink-template
The <<.def tv-wikilink-template>> [[variable|Variables]] controls the value of the `href` attribute on the HTML `a` element generated by the <<.wlink LinkWidget>> widget.
<<.this-is-static-link-variable>>
The variable is treated as if it was a [[macro|Macros]] with the following parameters:
;uri_encoded
: The title of the target tiddler of the link, but [[percent-encoded|Percent Encoding]]
;uri_doubleencoded
: The value of the <<.param uri_encoded>> parameter but percent-encoded again, i.e. with its `%` characters further converted to `%25`
> `\define tv-wikilink-template() ../tiddlers/$uri_encoded$.html`
The variable defaults to `#$uri_encoded$`.
See also the <<.vlink tv-get-export-link>> variable, which dominates over this one.

View File

@ -0,0 +1,12 @@
created: 20150228115540000
modified: 20150228130451000
title: tv-wikilink-tooltip Variable
tags: Variables [[Core Variables]] [[Configuration Variables]]
type: text/vnd.tiddlywiki
caption: tv-wikilink-tooltip
The <<.def tv-wikilink-tooltip>> [[variable|Variables]] specifies the default value for the <<.attr tooltip>> attribute of the <<.wlink LinkWidget>> widget.
It is often defined as a [[macro|Macros]], and its value parsed as inline WikiText.
<<.variable-examples "tv-wikilink-tooltip">>

View File

@ -0,0 +1,18 @@
created: 20150228102737000
modified: 20150228130415000
title: tv-wikilinks Variable
tags: Variables [[Core Variables]] [[Configuration Variables]]
type: text/vnd.tiddlywiki
caption: tv-wikilinks
The <<.def tv-wikilinks>> [[variable|Variables]] controls the behaviour of the <<.wlink LinkWidget>> widget.
The widget normally produces a link to a tiddler. But if this variable has the value <<.value no>>, the widget suppresses the link and simply displays the text that would otherwise have served as the link.
You can suppress links for a whole tiddler by placing the following line at the start of the tiddler's text:
> `\define tv-wikilinks() no`
This variable has no effect on external links, as those do not involve the <<.wid link>> widget.
<<.variable-examples "tv-wikilinks">>