Let's put everything we've learned so far about customizing TiddlyWiki together by building a useful and commonly requested tool. Several plugins offer prefabricated versions of the tool we're about to discuss, which you might or might not prefer to building your own, but creating our own will be educational at the least.
We know we can get at the backlinks of a tiddler by looking at the info section of a tiddler. In many types of wikis, however, it's convenient to have the backlinks much more obvious. Let's build some custom functionality to show all of the backlinks at the bottom of each tiddler without having to click on anything. While we're at it, let's summarize the forward links in the tiddler here, too: at the bottom of the tiddler, we'll have two columns, the left column showing all the forward links and the right column showing all the backward links. (You may notice that this is strikingly like the “related topics” view you can find in the footer of any section in this book – so no cheating by looking there!)
Most of this section will be presented as a series of exercises: you'll be given a small incremental step in the implementation to try on your own, and in the answer I will show one possible way to do it. At that point, you're free to either change your implementation to match the answer or attempt to continue with your own version.
Building the logic
Create a tiddler called $:/yourname/TiddlerLinkSummary. Make this tiddler display a simple bulleted list of all backlinks of the current tiddler. (Since we will need to make this more complex momentarily, use a $list widget, not a list-links macro.) Then make this content included at the bottom of every tiddler.
Edit $:/yourname/TiddlerLinkSummary to show a list of the forward links as well. We don't want the wikitext to get too repetitive, so create a procedure to hold the bits that are the same in both. You may find the subfilter filter operator helpful.
Add an excerpt for each link – in other words, grab the first 200 characters of each tiddler and show it under the title. This will help us remind us what the tiddler is about, if the title wasn't chosen carefully enough.
We can accomplish this by wikifying the tiddler – that is, processing the HTML, transclusions, and wikitext in it as if we were displaying the tiddler – and then taking just the beginning portion of it. Here's a partially completed procedure you can use to get an excerpt from a tiddler. Your task is to figure out what goes in the filtered transclusions (to get the wikitext of the tiddler and convert the rendered wikitext to just its first 200 characters), then call the procedure from an appropriate location.
\procedure excerptify(title)
<$wikify name="contents" text={{{ ... }}}>
<$text text={{{ ... }}} />...
</$wikify>
\endHint: The split[] filter operator with nothing in the square brackets can be used to split incoming text into individual characters. You may need to review the filter operators documentation.
Let's do a bit of formatting now. It probably will look better if the excerpt starts on a new line after the title, especially once we get this into two columns. An easy way to do that in HTML is to place the excerpt procedure call in a <div> tag (short for division), which is a generic way to group content together, so go ahead and do that and check that it works.
In addition, let's wrap the Links and Backlinks sections, including the titles, each in a div (you can do this within the procedure). We'll need to have them in separate divs to get them to appear in two columns.
Lastly, wrap the whole thing (both the Links and Backlinks sections) in one more div.
Aside from the excerpts appearing on separate lines from the tiddler titles, you should not see any difference in output yet – we've merely made it possible to style with CSS.
go to answerOne more step with the divs. In order to get them formatted correctly, we need to be able to identify each of them separately. The way we do this in HTML/CSS is by applying a class (that is, assigning a value to the class attribute of the HTML tag). Adjust the wikitext so that each div has a class. It's a good idea to prefix your class names (in CSS class names, the prefix is normally separated from the rest of the name by a hyphen -), as CSS classes apply globally. I'll prefix these with sib-links-.
Again, you won't see any changes in output yet.
go to answerImproving the formatting
Custom formatting can be added to tiddlers using a stylesheet. Stylesheets are written in the CSS (Cascading Style Sheets) language, an extremely powerful if slightly obtuse formatting language that controls the display of every web page you've ever looked at. You can either put a stylesheet in an individual tiddler within <style> tags (this is called an inline stylesheet) or make it global to the wiki. See Stylesheets if you know a little CSS and want more details on the options TiddlyWiki provides here.
Teaching you CSS is outside the scope of this book, so I'm just going to give you a stylesheet to use with this exercise. If you're interested in learning more, there are a wide variety of resources on the Internet.
<style>
div.sib-links-container {
border: 1px dashed white;
overflow: auto;
padding: 2px;
}
div.sib-links-container div ul {
list-style-type: none;
padding-left: 0;
}
div.sib-links-container div ul div.sib-links-excerpt {
padding-left: 1em;
color: <<colour muted-foreground>>;
}
div.sib-links-forward {
width: 50%;
float: left;
padding-right: 0.5em;
}
div.sib-links-backward {
width: 50%;
float: right;
padding-left: 0.5em;
}
</style>If you named the classes you put on your divs something different than I did, you'll need to replace the names in the part before each opening { (this part is called the CSS selector). Otherwise, just paste this at the bottom of the tiddler and save it, and your links should suddenly look much prettier.
Final tweaks
Make the size of the excerpt configurable via a configuration tiddler. Call the configuration tiddler $:/config/LinkExcerptLength.
In the stylesheet I provided, you may have noticed there is a macro call: <<colour muted-foreground>>. This macro is used to retrieve a color from the palette. The benefit is that if you change the palette of your wiki, the color of the excerpt text will change to something appropriate as well.
Find the definition of the colour macro and figure out how the CSS color value (it'll be a # and six numbers and letters) is retrieved.