Create TransclusionAsTemplateUsage.tid

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 ``{{<target>||<template>}}``. The default ``<target>`` is the [[current tiddler|CurrentTiddler]] (this is what we used in the above example). 
+
+! Examples
+
+!! A predefined template to render tags nicely
+
+You can apply the system template ``$:/core/ui/TagTemplate`` to a tag in order to see it as a tag pill with a drop-down menu:
+
+```
+{{Transclusion||$:/core/ui/TagTemplate}}
+```
+
+is rendered as {{Transclusion||$:/core/ui/TagTemplate}}
+
+!! An exercise
+
+Create three tiddlers A, B and C with the following content:
+
+!!! in A:
+
+```
+ Hello, my name is {{!!title}} and the last time I was modified is {{!!modified}}
+```
+
+!!! in B:
+
+```
+{{||A}}
+```
+
+!!! in C: 
+
+```
+{{B}}
+```
+
+# Can you make C print //"Hello, my name is C ..."// without referring to A directly? 
+# Can you make C print //"Hello, my name is A ..."// without modifying C?
+
+<$button set="$:/TransclusionAsTemplateUsageExerciseState1" setTo="show">Show the answers</$button>
+
+<$reveal type="match" state="$:/TransclusionAsTemplateUsageExerciseState1" text="show">
+
+# In tiddler C, replace ``{{B}}`` with ``{{||B}}``
+# In tiddler B, replace ``{{||A}}`` with ``{{A}}``
+
+<$button set="$:/TransclusionAsTemplateUsageExerciseState1" setTo="hide">Hide the answers</$button>
+</$reveal>
+
+See also [[Transclusion in WikiText]], TextReference, CurrentTiddler and TemplateTiddlers.