From 900738e79643c60cb82a627909694e225f5bc283 Mon Sep 17 00:00:00 2001 From: Erwan Moreau Date: Tue, 9 Dec 2014 14:42:41 +0000 Subject: [PATCH 1/3] Create TransclusionPrinciple.tid --- .../tiddlers/concepts/TransclusionPrinciple.tid | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 editions/tw5.com/tiddlers/concepts/TransclusionPrinciple.tid diff --git a/editions/tw5.com/tiddlers/concepts/TransclusionPrinciple.tid b/editions/tw5.com/tiddlers/concepts/TransclusionPrinciple.tid new file mode 100644 index 000000000..d52103e4d --- /dev/null +++ b/editions/tw5.com/tiddlers/concepts/TransclusionPrinciple.tid @@ -0,0 +1,14 @@ +created: 20141129194651420 +creator: Erwan +modified: 20141130195444237 +modifier: Erwan +tags: Transclusion +title: TransclusionPrinciple + +A transclusion consists in including some content from a tiddler A into another tiddler B //by reference//. + +This means that, instead of having the same content in two different places (as what happens if the content is "copy-pasted" from A to B), there is a special instruction in B which indicates that this part should be taken from tiddler A. The first advantage is that if something is modified in A, the modification appears automatically in B as well. Thus it is easier to maintain inter-dependent content, since every piece of content is written in a single place, but can be viewed from many. + +In TiddlyWiki the concept of transclusion plays a very important role because the [[Philosophy of Tiddlers]] is to connect small pieces of information together. But the concept is extended even further to allow for various kinds of useful features. To learn how to use it, see TransclusionBasicUsage and TransclusionAsTemplateUsage. + +See also: TransclusionBasicUsage, TransclusionAsTemplateUsage, [[Transclusion in WikiText]], TextReference, TemplateTiddlers and TranscludeWidget. From 46e6fb195779fbbc0d3354d448d1196fb5f6fb7c Mon Sep 17 00:00:00 2001 From: Erwan Moreau Date: Tue, 9 Dec 2014 14:44:28 +0000 Subject: [PATCH 2/3] Create TransclusionBasicUsage.tid --- .../concepts/TransclusionBasicUsage.tid | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 editions/tw5.com/tiddlers/concepts/TransclusionBasicUsage.tid diff --git a/editions/tw5.com/tiddlers/concepts/TransclusionBasicUsage.tid b/editions/tw5.com/tiddlers/concepts/TransclusionBasicUsage.tid new file mode 100644 index 000000000..06402d365 --- /dev/null +++ b/editions/tw5.com/tiddlers/concepts/TransclusionBasicUsage.tid @@ -0,0 +1,44 @@ +created: 20141129201509859 +creator: Erwan +modified: 20141130194810119 +modifier: Erwan +tags: Transclusion +title: TransclusionBasicUsage + +! Simple transclusion + +To include some content from ~TiddlerA into ~TiddlerB, edit the latter and write: + +``` +This is the content of TiddlerA: {{TiddlerA}} +``` + + + As a result, the content of the field ``text`` (i.e. the main content) of ~TiddlerA is rendered in ~TiddlerB. + +! Usage + + +The notation ``{{TiddlerA}}`` is actually a shortcut for ``{{TiddlerA!!text}}``. This is because by default the transcluded field is ``text``, but any other [[field|TiddlerFields]] can be used explicitly. For example, you can print the last time ~TiddlerA was modified using: + +``` +TiddlerA was modified on {{TiddlerA!!modified}} +``` + +The ``{{...!!...}}`` notation is also used to display the content of a field from the current tiddler, for example: + +``` +The current tiddler was modified on {{!!modified}} +``` + +This is because displaying a field is also a form of transclusion. In this case, the notation ``{{!!modified}}`` used in ~TiddlerB is equivalent to ``{{TiddlerB!!modified}}``. In other words, the default value for the part before ``!!`` is the title of the current tiddler. + +! Recursion errors + +Notice that using ``{{!!text}}`` or ``{{}}`` causes an error (//Recursive transclusion error in transclude widget//), because it does not make sense to include the content of the current tiddler into the content of the current tiddler (that is, into itself). Whenever you encouter this error message, it means that you are trying to include something into itself, directly or not (for example if tiddler A transcludes tiddler B which transcludes tiddler C which, in turn, transcludes tiddler A). + +! Going further + +In TiddlyWiki, transclusions are not limited to including raw content like the above. To learn about a more advanced kind of transclusion, see TransclusionAsTemplateUsage. + +See also: TransclusionAsTemplateUsage, [[Transclusion in WikiText]], TextReference, and TiddlerFields. From 63c441d3e85b08496749cdc9d0122658aa23de89 Mon Sep 17 00:00:00 2001 From: Erwan Moreau Date: Tue, 9 Dec 2014 14:45:40 +0000 Subject: [PATCH 3/3] Create TransclusionAsTemplateUsage.tid --- .../concepts/TransclusionAsTemplateUsage.tid | 92 +++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 editions/tw5.com/tiddlers/concepts/TransclusionAsTemplateUsage.tid diff --git a/editions/tw5.com/tiddlers/concepts/TransclusionAsTemplateUsage.tid b/editions/tw5.com/tiddlers/concepts/TransclusionAsTemplateUsage.tid new file mode 100644 index 000000000..b0667861e --- /dev/null +++ b/editions/tw5.com/tiddlers/concepts/TransclusionAsTemplateUsage.tid @@ -0,0 +1,92 @@ +created: 20141129210304238 +creator: Erwan +modified: 20141209142028738 +modifier: Erwan +tags: Transclusion +title: TransclusionAsTemplateUsage + +! Problem + + +In TransclusionBasicUsage we have seen how to include the content of a tiddler A into a tiddler B. Now suppose that tiddler A contains: + +``` +@@background-color:yellow; +Hello, my title is {{!!title}} +@@ +``` + +This makes tiddler A display its title with a yellow background (see [[Styles and Classes in WikiText]] to learn about CSS style). Imagine that you want to display the title in the same way in tiddler B. But you don't want to copy/paste the style instructions, because you might want to change the background colour later and you want to keep it consistent among tiddlers. This looks like a typical case of transclusion, so let's try to transclude tiddler A in tiddler B the usual way with ``{{A}}``. You should see the following content in tiddler B: + +<<< +@@background-color:yellow; +Hello, my title is A +@@ +<<< + +The style is applied as expected, but the title is wrong: we want ``{{!!title}}`` to refer to the target tiddler B, and not the source tiddler A. + +! Solution + +Thankfully TiddlyWiki provides a way to do exactly that, using ''templates''. In this case, the source tiddler A is called the [[TemplateTiddler|TemplateTiddlers]], and it is //applied// to tiddler B using the notation ``{{||A}}``. The difference is that any TextReference which does not refer explicitly to a specific tiddler is applied to the [[current tiddler|CurrentTiddler]], that is, the target tiddler. As a result, tiddler B now looks as expected: + +<<< +@@background-color:yellow; +Hello, my title is B +@@ +<<< + +! Usage + +Transcluding via a template is like applying a mask: assuming that the source tiddler contains generic references (like eye holes in a mask), these will be replaced with the target tiddlers values (like the eyes of the person who wears the mask). + +A template can be applied to any tiddler, not necessarily the current one. This is achieved using the full notation ``{{||