Note: An alternative skin, TW4MW (work in progress), is available from the user preferences.
Transclusion
TiddlyWiki Community Wiki
This page is still incomplete. You can help by contributing to its expansion.
Please improve the article, or discuss the issue on the talk page.
Using the Tiddler macro, contents of one tiddler can be embedded ("transcluded") from another tiddler:
<<tiddler [[Foo]]>>
Contents |
[edit] Partial Transclusion
With the use of slices and sections, specific parts can be transcluded from another tiddler:
<<tiddler [[tiddler::sliceLabel]]>> <<tiddler [[tiddler##sectionHeading]]>>
[edit] Examples
Tiddler: Slices
label1: lorem label2: ipsum label3: dolor |label4|sit| |label5|amet| |label6|consectetur|
<<tiddler [[Slices::label1]]>>
Tiddler: Sections
!Heading1 Lorem ipsum dolor sit amet. !Heading2 Consectetur adipisicing elit. !Heading3 Sed do eiusmod tempor incididunt ut labore.
<<tiddler [[Sections##Heading1]]>>
[edit] Parametric Transclusion
Using the NewTiddler macro's with: parameter, placeholders ($1-$9) in the transcluded contents can be replaced with the desired value:
<<tiddler [[Foo]] with:"bar" "baz" ...>>
[edit] Examples
Tiddler: QuoteTemplate
<<<
$1
<<<
{{{$2}}}
Tiddler: Quotations
<<tiddler [[QuoteTemplate]] with:"Alas poor Yorick" "Shakespeare">>
This will show:
Alas Poor YorickShakespeare
cf. [tw] templates / transclusion (parametric)
[edit] Editing Transcluded Contents
- TiddlerWithEditPlugin: adds "double-click to edit source" capabilities to the core Tiddler macro
- EditTiddlerPlugin: embeds an "edit" link in tiddler content to invoke edit on any specified tiddler title
[edit] StyleSheet Transclusion
Within Style Sheets, PrettyLinks are treated like import statements; the contents of the targeted tiddler are included as CSS code.
[edit] Transcluded Html Scripts
by Eric
Transclusions can be used generate program- driven output, embedded in specific
tiddler content (like an inline script or a plugin-defined macro).
Transclusions are invoked by using the
<<tiddler TiddlerName with: param param param ...>>
syntax. The 'param' values are automatically inserted in place of
any 'substitution markers' ("$1" through "$9") that are embedded in the
transcluded content. This allows you to use the transclusion as if it was a
macro function: passing in parameter values and generating enhanced output in
response.
Some transclusions are simple substitutions, allowing you to use an abbreviated
syntax to render pre-formatted blocks of content, like this:
<<tiddler ShowQuotation with: [[...quote...]] [[author]]>>
where ShowQuotation contains:
$2 wrote:
{{{
$1
}}}
Transclusions can do much more than simply insert a few values into a
pre-defined format. By using a combination of 'hidden sections' and some
cleverly written 'evaluated parameters' invoked from the <<tiddler>> macro, it
is possible to build some complex programmed behaviors
into a transcluded tiddler.
However, while macros and inline scripts can use virtually any javascript coded
logic you can imagine, transclusions only contain standard TW syntax, without
relying upon installation of any supporting plugins (i.e.,
InlineJavascriptPlugin). Although this limits their abilities somewhat, there
are still a wide variety of programmatically-generated output and/or behaviors
that they can produce.
In fact, when possible, I have been converting many of my previously written
TiddlyTools inline scripts into 'transclusions', in order to completely
eliminate their dependence on InlineJavascriptPlugin. By using only TW native
syntax, it allows these former scripts to work properly and consistently,
regardless of whether they are installed in an empty TW document or one that
has been highly customized with lots of plugins.
For the current listing of 'transclusions' available on TiddlyTools, see:
http://www.TiddlyTools.com#txtCatalogTab:transclusions
