Note: An alternative skin, TW4MW (work in progress), is available from the user preferences.

TiddlyWiki Community Wiki

[edit] Introduction

TiddlyTemplating templates are tiddlers like everything else in a TiddlyWiki. In fact, any tiddler can be used as a template.

To help explain how to write templates, the following example will go through the process of creating a series of templates for use in constructing a custom RSS feed.

[edit] Worked Example: Creating an RSS feed

For instance, let's say you want to create a RSS feed that looks like this:

<?xml version="1.0"?>
<rss version="2.0">
<channel>
<title>TiddlyTemplating</title>
<link>http://www.example.com/</link>
<description>my top content</description>
<language>en-us</language>
<copyright>Copyright <span>Mon, 21 April 2008 12:12:21 +01:00</span> Author</copyright>
<pubDate><span>Mon, 21 April 2008 12:12:21 +01:00</span></pubDate>
<lastBuildDate><span>Mon, 21 April 2008 12:12:21 +01:00</span></lastBuildDate>
<docs>http://blogs.law.harvard.edu/tech/rss</docs>
<generator>TiddlyWiki 2.4.0</generator>
<item>
	<title>Article 2</title>
	<description>Lovely stuff this content</description>
	<category>docs</category><category>rss</category>
	<link>http://www.example.com/#Article%202</link>
	<pubDate>22 January 2008</pubDate>
</item>
<item>
	<title>Article 1</title>
	<description>Lovely stuff this data, yeah baby!</description>
	<category>docs</category><category>rss</category>
	<link>http://www.example.com/#Article%201</link>
	<pubDate>22 January 2008</pubDate>
</item>
</channel>
</rss>

[edit] Part 1: replacing repeating elements with nested templates

The approach to turning this into templates is to look for the highest-level repeating elements, which in this case are the <item> elements. We recognise that each one of these contains information gleaned from a tiddler, so we would make the decision that this is the point to introduce a nested call to templateTiddlers. We will also reference a sub-template to customize the output for each tiddler; so, the next iteration of this template, which we will call "RssTemplate" is this:

<?xml version="1.0"?>
<rss version="2.0">
<channel>
<title>TiddlyTemplating</title>
<link>http://www.example.com/</link>
<description>my top content</description>
<language>en-us</language>
<copyright>Copyright <span>Mon, 21 April 2008 12:12:21 +01:00</span> Author</copyright>
<pubDate><span>Mon, 21 April 2008 12:12:21 +01:00</span></pubDate>
<lastBuildDate><span>Mon, 21 April 2008 12:12:21 +01:00</span></lastBuildDate>
<docs>http://blogs.law.harvard.edu/tech/rss</docs>
<generator>TiddlyWiki 2.4.0</generator>
<!--<<templateTiddlers RssItemTemplate filter:"[tag[rss]]">>-->
</channel>
</rss>

The filter expression given as a parameter to templateTiddlers is used to filter the TiddlyWiki store for a set of tiddlers matching the expression. In this case, the tiddlers returned all have the tag "rss". For more information on filter expressions, see the filterTiddlers page.

Note that the standard TiddlyWiki syntax for calling macros, "<<macroName>>", is wrapped in HTML comments here - this is so that the templates are valid HTML and play nicely in text editors. The extended syntax is not compulsory.

[edit] Part 2: creating the sub-templates for repeated elements

The reference to "RssItemTemplate" in the templateTiddlers macro call above is for a template we haven't created yet. The method for creating sub-templates starts with condensing what we have cut from the top-level template so that it only describes the repeating structure we previously identified. Here's what we cut:

<item>
	<title>Article 2</title>
	<description>Lovely stuff this content</description>
	<category>docs</category><category>rss</category>
	<link>http://www.example.com/#Article%202</link>
	<pubDate>22 January 2008</pubDate>
</item>
<item>
	<title>Article 1</title>
	<description>Lovely stuff this data, yeah baby!</description>
	<category>docs</category><category>rss</category>
	<link>http://www.example.com/#Article%201</link>
	<pubDate>22 January 2008</pubDate>
</item>

We can reduce this easily by cutting out the second repetition of the <item> element, and save this as RssItemTemplate:

<item>
	<title>Article 2</title>
	<description>Lovely stuff this content</description>
	<category>docs</category><category>rss</category>
	<link>http://www.example.com/#Article%202</link>
	<pubDate>22 January 2008</pubDate>
</item>

At this point, we can recognise that this structure contains its own repeating elements, in the <category> tag. As we did before, we need to cut these out and add another nested template:

<item>
	<title>Article 2</title>
	<description>Lovely stuff this content</description>
	<!--<<templateTags RssItemCategoryTemplate>>-->
	<link>http://www.example.com/#Article%202</link>
	<pubDate>22 January 2008</pubDate>
</item>

Note the use of "templateTags" rather than "templateTiddlers" here; this is so that the items that are looped over are the active tiddler's tags rather than the set of tiddlers returned using the filter expression. Finally, we'll need to create the RssItemCategoryTemplate we've just referenced.

Having cut this:

<category>docs</category><category>rss</category>

We create RssItemCategoryTemplate in one line:

<category><!--<<view tags>>--></category>

This is the first occurrence of the view macro to pull content into the output. More on that below. At this point, you can test that the templating is working as expected by running this macro inside a tiddler:

<<templateTiddlers RssTemplate>>

[edit] Part 3: filling in the details

Now that we have our template structure laid out properly, it is time to add the content to the feed. This comes from the tiddlers tagged with "rss" and from the wider TiddlyWiki. The view macro can be used extensively to pull data from tiddlers, and we also take advantage of the today macro and the message macro. The lists below outline which macros are used to get data out of the TiddlyWiki and the completed templates and shown following.

[edit] RssTemplate

In this case, we decide to use the text from the TiddlyWiki SiteTitle tiddler as the feed title. We could insert this using the Tiddler macro, although this adds a "span" wrapper element and wikifies the tiddler content. We can use another call to templateTiddlers with the tiddler in question as the template - it will then output the content of that tiddler.

Feed title: <<templateTiddlers SiteTitle>> Feed URL: <<templateTiddlers SiteURL>> Feed description: <<templateTiddlers SiteSubtitle>> Date of publishing: <<today "ddd, DD MMM YYYY 0hh:0hh:0ss TZD">> (for more info on date format strings, please see the formatString page) TiddlyWiki version number: <<message version.major>>.<<message version.minor>>.<<message version.revision>>

<?xml version="1.0"?>
<rss version="2.0">
<channel>
<title><!--<<templateTiddlers SiteTitle>>--></title>
<link><!--<<templateTiddlers SiteURL>>--></link>
<description><!--<<templateTiddlers SiteSubtitle>>--></description>
<language>en-us</language>
<copyright>Copyright <!--<<today "ddd, DD MMM YYYY 0hh:0hh:0ss TZD">>--> <!--<<message config.options.txtUserName>>--></copyright>
<pubDate><!--<<today "ddd, DD MMM YYYY 0hh:0hh:0ss TZD">>--></pubDate>
<lastBuildDate><!--<<today "ddd, DD MMM YYYY 0hh:0hh:0ss TZD">>--></lastBuildDate>
<docs>http://blogs.law.harvard.edu/tech/rss</docs>
<generator>TiddlyWiki <!--<<message version.major>>-->.<!--<<message version.minor>>-->.<!--<<message version.revision>>--></generator>
<!--<<templateTiddlers RssItemTemplate filter:"[tag[rss]]">>-->
</channel>
</rss>

[edit] RssItemTemplate

Tiddler title: <<view title>> Tiddler text: <<view text>> Permalink to the tiddler: <<permalink>> (macro created for this purpose) Date item last changed: <<view modified date>>

<item>
	<title><!--<<view title>>--></title>
	<description><!--<<view text>>--></description>
	<!--<<templateTags RssItemCategoryTemplate>>-->
	<link><!--<<permalink>>--></link>
	<pubDate><!--<<view modified date>>--></pubDate>
</item>

[edit] RssItemCategoryTemplate

We have already seen the finished template, but it is listed here for completeness.

Tiddler tag: <<view tags>>

<category><!--<<view tags>>--></category>

[edit] Part 4: running the templating

Now all the templates are finished, you can run the templating process and create your RSS feed inside a tiddler using a call to templateTiddlers:

<<templateTiddlers RssTemplate>>

Because this will be outputting XML into the tiddler, you won't see the tags unless you view the page source. Read on for a method to output the RSS feed to an external file, where you will be more easily able to see the XML structure.

[edit] Part 5: (advanced) overriding the current RSS saving mechanism

As you've just created a mechanism for creating custom RSS feeds, you might want to replace the existing RSS feed that is created when you save your TiddlyWiki. To do this, override the existing generateRss function in a new plugin (a tiddler tagged with "SystemConfig"), like so:

var generateRssOld = generateRss;
 
generateRss = function()
{
	return expandTemplate("RssTemplate") || generateRssOld();
};