TiddlyWiki5/editions/tw5.com/tiddlers/concepts/TextReference.tid

created: 20130827075900000
modified: 20161216173541948
tags: Concepts
title: TextReference
type: text/vnd.tiddlywiki

A TextReference is a general purpose way to describe a fragment of text as either a field of a tiddler, or an index within a [[data tiddler|DataTiddlers]].

In different situations, text references can be used to retrieve values, or to specify a value that should be modified.

A TextReference consists of several parts:

* The title of the target tiddler. If omitted, it defaults to the [[Current Tiddler]]
* Either one of:
** The name of a field (marked with `!!`)
** The name of an index within a [[data tiddler|DataTiddlers]] (marked with `##`)
* If both the field and index are omitted, the text field is used as the default

Most of the parts of a text reference can be optional:

* `tiddlerTitle` - the text [[field|TiddlerFields]] of the specified tiddler
* `tiddlerTitle!!field` - a [[tiddler field|TiddlerFields]] (eg, `modified`, `modifier`, `type` etc)
* `!!field` - a [[field|TiddlerFields]] of the current tiddler
* `tiddlerTitle##propertyIndex` - extracts a named property from DataTiddlers

Text references can be used in several places:

* As [[indirect parameters|Filter Parameter]] within [[Filters]] (eg, `<$list filter="[tag{MyTag!!name}]"/>`)
* As [[indirect attributes|HTML in WikiText]] of an element or widget (eg, `<$widget attrib={{Title!!description}}/>`)
* As the operand of a shortcut transclusion (eg, `{{MyTiddler!!title}}`)
* As the `state` attribute of the RevealWidget and the LinkCatcherWidget

<$macrocall $name=".tip" _="""Note the distinction between a text reference such as `foo!!bar` and a transclusion of a text reference such as `{{foo!!bar}}`"""/>
Clarify TextReference documentation Prompted by this comment: https://github.com/Jermolene/TiddlyWiki5/pull/1721#issuecomment-10217516 5 2015-05-18 18:07:14 +00:00			`created: 20130827075900000`
Improve text reference documentation 2016-12-16 17:36:11 +00:00			`modified: 20161216173541948`
More reference docs mangling 2014-09-11 14:52:47 +00:00			`tags: Concepts`
Docs updates 2013-08-27 08:01:40 +00:00			`title: TextReference`
Clarify TextReference documentation Prompted by this comment: https://github.com/Jermolene/TiddlyWiki5/pull/1721#issuecomment-10217516 5 2015-05-18 18:07:14 +00:00			`type: text/vnd.tiddlywiki`
Docs update 2012-06-19 07:56:45 +00:00
Updated text reference docs 2016-12-17 12:25:40 +00:00			`A TextReference is a general purpose way to describe a fragment of text as either a field of a tiddler, or an index within a [[data tiddler\|DataTiddlers]].`

			`In different situations, text references can be used to retrieve values, or to specify a value that should be modified.`
Docs update 2012-06-19 07:56:45 +00:00
Improve text reference documentation 2016-12-16 17:36:11 +00:00			`A TextReference consists of several parts:`

			`* The title of the target tiddler. If omitted, it defaults to the [[Current Tiddler]]`
			`* Either one of:`
			** The name of a field (marked with `!!`)
			** The name of an index within a [[data tiddler\|DataTiddlers]] (marked with `##`)
			`* If both the field and index are omitted, the text field is used as the default`

			`Most of the parts of a text reference can be optional:`
Docs update 2012-06-19 07:56:45 +00:00
Clarify TextReference documentation Prompted by this comment: https://github.com/Jermolene/TiddlyWiki5/pull/1721#issuecomment-10217516 5 2015-05-18 18:07:14 +00:00			* `tiddlerTitle` - the text [[field\|TiddlerFields]] of the specified tiddler
			* `tiddlerTitle!!field` - a [[tiddler field\|TiddlerFields]] (eg, `modified`, `modifier`, `type` etc)
			* `!!field` - a [[field\|TiddlerFields]] of the current tiddler
			* `tiddlerTitle##propertyIndex` - extracts a named property from DataTiddlers
Docs updates 2013-08-27 08:01:40 +00:00
			`Text references can be used in several places:`

Overhaul the filter operator documentation: part 2 2015-01-24 21:18:44 +00:00			* As [[indirect parameters\|Filter Parameter]] within [[Filters]] (eg, `<$list filter="[tag{MyTag!!name}]"/>`)
Improve text reference documentation 2016-12-16 17:36:11 +00:00			* As [[indirect attributes\|HTML in WikiText]] of an element or widget (eg, `<$widget attrib={{Title!!description}}/>`)
Docs updates 2013-08-27 08:01:40 +00:00			* As the operand of a shortcut transclusion (eg, `{{MyTiddler!!title}}`)
			* As the `state` attribute of the RevealWidget and the LinkCatcherWidget
Improve text reference documentation 2016-12-16 17:36:11 +00:00
Updated text reference docs 2016-12-17 12:25:40 +00:00			<$macrocall $name=".tip" _="""Note the distinction between a text reference such as `foo!!bar` and a transclusion of a text reference such as `{{foo!!bar}}`"""/>
Improve text reference documentation 2016-12-16 17:36:11 +00:00