How to make a Template in TiddlyWebPages
Since I announced TiddlyWebPages, I've been meaning to write a quick tutorial explaining how to make templates and define custom URLs for use on your site. In this post, I'll just cover templates and save URLs for another day. So let's start off at the point where you've installed TiddlyWeb, you have some content in your store, and you've installed TiddlyWebPages.
Right, the first step is to create a bag called templates and a bag called urls. Within the templates bag, you'll need to create a "wrapper" template. This will be the wrapper for all your content, so you can add links to your CSS definitions and Javascript files (or anything else) here without needing to include such things in every template. It needs to be called "Default" as it's the first one (and you need some sort of default right?) and while you can add other wrappers, we're not going into that quite yet. For now though, get the Default tiddler in the TiddlyWebPages GitHub directory at http://github.com/bengillies/TiddlyWeb-Plugins/raw/master/tw_pages/Default.tid and put it into your templates bag. You'll notice a couple of extra fields. list_tiddlers lets you specify the default template to use with a list of tiddlers (be it a bag, recipe or search results) while single_tiddlers does the same thing but for displaying a single tiddler only.
Now that's done, you can start adding templates. Now, as templates are all tiddlers themselves, you may want to just copy some from somebody else (my templates for example), but as this post is entitled "How to make a template", we'll assume you want to start from scratch.
Create a tiddler in the templates bag entitled "List". This will simply list all tiddlers in the bag/recipe that you are in, showing both the title, and the text. Next, enter the following information into the body of the tiddler:
Let's take a look at that line by line shall we?
This line starts a loop over all tiddlers, giving each tiddler in the list (called base, short for "base tiddlers") a name that you can refer to it with of "tiddler". "base" is a value that TiddlyWebPages provides you with to access the base set of tiddlers in the bag/recipe.
You can add other tiddlers, pre-formatted with another template, by specifying the template/recipe combination as a field in the template you want to include it in. For example, let's say you have created a "Header" template already and want to include it in your "List" template. Let's say that the tiddler that defines your header, is returned by the "my_header" recipe. To do that, you'd add a field to the "List" template specifying the "Header" template and the "my_header" recipe:
In this definition, "Header" is the title of the field, and specifies the template you want to use, while "my_recipe" specifies the recipe that you want to use. Anything after the question mark is run as a filter on the recipe. In this case, we are selecting the ListHeading tiddler from the recipe. The ability to filter recipes is especially useful for sorting tiddlers, as recipes cannot sort by default.
Adding this Header into the template, would produce a result as follows:
Notice the new variable called "extra". This contains the HTML for any extra templates you have specified in the tiddler's "fields" (as above). This gives two main variables that you can use: base; and extra. Other variables are: prefix - any server prefix you have defined in tiddlywebconfig.py; query - a key/value list of all items in the query string of the url; root_vars - a key/value list of any patterns that you have specified in your URL (by default, this will contain the tiddler name, in root_vars['tiddler'], the recipe name in root_vars['recipe'] and the bag name in root_vars['bag']).
You can put HTML wherever you like, which can form the basis of your template. The tiddler.title is enclosed in double braces - this tells TiddlyWebPages (actually the Jinja2 templating engine) that tiddler.title is a variable and you want to write its value into the page. The {% ... %} pattern tells Jinja2 that you want to run something without writing the output to the page. In the example above, this would be the for loop.
These lines just output the text of the tiddler and close the for loop. Optionally, you can choose to wikify the text by passing it through a filter and specifying a recipe name to use when creating links. If you did this with the recipe "sitecontent" (the recipe on my site that contains all my tiddlers) then you'd end up with the following:
In addition to all the standard Jinja filters and the wikifier, there is another filter called "shorten" that you can use to safely shorten HTML without worrying about cutting off closing tags.
Now that you've done that, you'll want to test it. So go to the tiddlers in one of your bags, and append ".List" to the end of tiddlers to see the result. You can try this on my site by going to http://bengillies.net/.a/recipes/blog/tiddlers.ContentList (my template is a bit more complicated though).
Finally, please read through the Jinja2 documentation to get a better idea of what you can accomplish. You can find it at http://jinja.pocoo.org/2/documentation/templates
You can also view my Templates at http://bengillies.net/.a/bags/templates/tiddlers If you want to use any of them yourself.
Right, the first step is to create a bag called templates and a bag called urls. Within the templates bag, you'll need to create a "wrapper" template. This will be the wrapper for all your content, so you can add links to your CSS definitions and Javascript files (or anything else) here without needing to include such things in every template. It needs to be called "Default" as it's the first one (and you need some sort of default right?) and while you can add other wrappers, we're not going into that quite yet. For now though, get the Default tiddler in the TiddlyWebPages GitHub directory at http://github.com/bengillies/TiddlyWeb-Plugins/raw/master/tw_pages/Default.tid and put it into your templates bag. You'll notice a couple of extra fields. list_tiddlers lets you specify the default template to use with a list of tiddlers (be it a bag, recipe or search results) while single_tiddlers does the same thing but for displaying a single tiddler only.
Your First Template
Now that's done, you can start adding templates. Now, as templates are all tiddlers themselves, you may want to just copy some from somebody else (my templates for example), but as this post is entitled "How to make a template", we'll assume you want to start from scratch.
Create a tiddler in the templates bag entitled "List". This will simply list all tiddlers in the bag/recipe that you are in, showing both the title, and the text. Next, enter the following information into the body of the tiddler:
{% for tiddler in base %}
<h1>{{tiddler.title}}</h1>
{{tiddler.text}}
{% endfor %}
<h1>{{tiddler.title}}</h1>
{{tiddler.text}}
{% endfor %}
Let's take a look at that line by line shall we?
{% for tiddler in base %}
This line starts a loop over all tiddlers, giving each tiddler in the list (called base, short for "base tiddlers") a name that you can refer to it with of "tiddler". "base" is a value that TiddlyWebPages provides you with to access the base set of tiddlers in the bag/recipe.
You can add other tiddlers, pre-formatted with another template, by specifying the template/recipe combination as a field in the template you want to include it in. For example, let's say you have created a "Header" template already and want to include it in your "List" template. Let's say that the tiddler that defines your header, is returned by the "my_header" recipe. To do that, you'd add a field to the "List" template specifying the "Header" template and the "my_header" recipe:
Header: my_recipe?select=title:ListHeading
In this definition, "Header" is the title of the field, and specifies the template you want to use, while "my_recipe" specifies the recipe that you want to use. Anything after the question mark is run as a filter on the recipe. In this case, we are selecting the ListHeading tiddler from the recipe. The ability to filter recipes is especially useful for sorting tiddlers, as recipes cannot sort by default.
Adding this Header into the template, would produce a result as follows:
{{extra['Header']}}
{% for tiddler in base %}
<h1>{{tiddler.title}}</h1>
{{tiddler.text}}
{% endfor %}
{% for tiddler in base %}
<h1>{{tiddler.title}}</h1>
{{tiddler.text}}
{% endfor %}
Notice the new variable called "extra". This contains the HTML for any extra templates you have specified in the tiddler's "fields" (as above). This gives two main variables that you can use: base; and extra. Other variables are: prefix - any server prefix you have defined in tiddlywebconfig.py; query - a key/value list of all items in the query string of the url; root_vars - a key/value list of any patterns that you have specified in your URL (by default, this will contain the tiddler name, in root_vars['tiddler'], the recipe name in root_vars['recipe'] and the bag name in root_vars['bag']).
<h1>{{tiddler.title}}</h1>
You can put HTML wherever you like, which can form the basis of your template. The tiddler.title is enclosed in double braces - this tells TiddlyWebPages (actually the Jinja2 templating engine) that tiddler.title is a variable and you want to write its value into the page. The {% ... %} pattern tells Jinja2 that you want to run something without writing the output to the page. In the example above, this would be the for loop.
{{tiddler.text}}
{% endfor %}
{% endfor %}
These lines just output the text of the tiddler and close the for loop. Optionally, you can choose to wikify the text by passing it through a filter and specifying a recipe name to use when creating links. If you did this with the recipe "sitecontent" (the recipe on my site that contains all my tiddlers) then you'd end up with the following:
{{tiddler.text|wikifier('sitecontent')}}
In addition to all the standard Jinja filters and the wikifier, there is another filter called "shorten" that you can use to safely shorten HTML without worrying about cutting off closing tags.
Now that you've done that, you'll want to test it. So go to the tiddlers in one of your bags, and append ".List" to the end of tiddlers to see the result. You can try this on my site by going to http://bengillies.net/.a/recipes/blog/tiddlers.ContentList (my template is a bit more complicated though).
Finally, please read through the Jinja2 documentation to get a better idea of what you can accomplish. You can find it at http://jinja.pocoo.org/2/documentation/templates
You can also view my Templates at http://bengillies.net/.a/bags/templates/tiddlers If you want to use any of them yourself.
Comments