Merge pull request #935 from Eucaly/variables

add WidgetVariable documentation

editions/tw5.com/tiddlers/filters/FilterOperator fields.tid

@@ -1,5 +1,6 @@
+caption: fields
 created: 20140924115616653
-modified: 20140924115627781
+modified: 20141002150019737
 tags: Filters
 title: FilterOperator: fields
 type: text/vnd.tiddlywiki

editions/tw5.com/tiddlers/variables/Variables.tid

@@ -0,0 +1,15 @@
+created: 20141002133113496
+modified: 20141002230631361
+tags: Reference
+title: Variables
+type: text/vnd.tiddlywiki
+
+Variables together with [[Widgets]] and [[Macros]] are essential for dynamic WikiText.
+
+You can define your own [[Variables in WikiText]] or use built-in variables.
+
+More detailed information of built-in variables could be found in below:
+
+<<list-links "[tag[Variables]]">>
+
+See also DumpVariablesMacro

editions/tw5.com/tiddlers/variables/WidgetVariable_ currentTiddler.tid

@@ -0,0 +1,22 @@
+caption: currentTiddler
+created: 20141001232824187
+modified: 20141002161518301
+tags: Variables
+title: WidgetVariable: currentTiddler
+type: text/vnd.tiddlywiki
+
+! Mechanism
+
+The ''currentTiddler'' variable containes the title of the current tiddler. 
+
+The ListWidget assigns the list result to the ''currentTiddler'' variable, unless the `variable` attribute is specified.
+
+A couple of [[Widgets]] and [[Macros]] by default apply to the tiddler according to the ''currentTiddler'' variable. 
+
+The TranscludeWidget (or WikiText `{{||TemplateTitle}}`) transcludes a tiddler without changing the ''currentTiddler'' variable.
+
+! Using currentTiddler Variable
+
+These mechanisms together allow you to write references like `<$view field="title" format="link"/>` in TemplateTiddlers or inside the ListWidget hierarchy without explicitly specifying the tiddler that it applies to.
+
+See also [[WidgetVariable: storyTiddler]]

editions/tw5.com/tiddlers/variables/WidgetVariable_ storyTiddler.tid

@@ -0,0 +1,10 @@
+caption: storyTiddler
+created: 20141001232753952
+modified: 20141002133957245
+tags: Variables
+title: WidgetVariable: storyTiddler
+type: text/vnd.tiddlywiki
+
+The ''storyTiddler'' variable is set by the  [[default viewtemplate|$:/core/ui/ViewTemplate]] to the name of the current tiddler within tiddlers in the story river, and is not defined within the sidebar.
+
+See also [[WidgetVariable: currentTiddler]]

editions/tw5.com/tiddlers/variables/WidgetVariable_ transclusion.tid

@@ -0,0 +1,36 @@
+caption: transclusion
+created: 20141002004621385
+modified: 20141002162057822
+tags: Variables
+title: WidgetVariable: transclusion
+type: text/vnd.tiddlywiki
+
+! Mechanism 
+The ''transclusion'' variable is set automatically by the transclude widget to contain a string that identifies the position of the current node within the widget tree. In the sidebar it is set to `{|$:/core/ui/PageTemplate/sidebar|||}` and within the tiddler "HelloThere" in the story river it is set to `{HelloThere|HelloThere|||}`. Each nested level of transclusion appends another curly bracketed list of symbols.
+
+The QualifyMacro uses the ''transclusion'' variable to identify the stack of transcluded tiddlers.
+
+! Example
+
+```
+\define mymacro()
+Hello from mymacro
+<$list filter="[<transclusion>prefix[{|$:/core/ui/PageTemplate/sidebar|||}]]" emptyMessage="in a tiddler">
+	in the sidebar
+</$list>
+\end
+
+<<mymacro>>
+```
+
+Result in story tiddler
+
+```
+Hello from mymacro in a tiddler
+```
+
+Result in the sidebar
+
+```
+Hello from mymacro in the sidebar
+```

editions/tw5.com/tiddlers/wikitext/Variables in WikiText.tid

@@ -0,0 +1,28 @@
+caption: Variables
+created: 20141002141231992
+modified: 20141002230751664
+tags: WikiText
+title: Variables in WikiText
+type: text/vnd.tiddlywiki
+
+! Defining Variables
+Variables contains values defined by [[Widgets]].
+Variables are available within the widget that defines them, and the child widgets in the widget tree.
+
+Variables are defined by:
+
+* TiddlyWiki core and viewtemplate
+* SetWidget
+* ListWidget
+* [[Macro definition|Macros in WikiText]]
+
+! Using Variables
+
+Variables are used in:
+
+* Variable substitution `$(name)$`
+* Concise shortcut  `<<name>>`
+* [[Filter expression|Introduction to Filters]] `[operator<variable-operand>]`
+* Some default behaviors of [[Widgets]]
+
+See also [[currentTiddler|WidgetVariable: currentTiddler]] variable and built-in [[variables|Variables]].