Introduction

This plugin enables TiddlyWiki to embed a modified copy of itself (an "innerwiki") with overlaid graphics. The primary motivation is to be able to produce screenshot illustrations that are automatically up-to-date with the appearance of TiddlyWiki as it changes over time, or to produce the same screenshot in different languages.

In the browser, innerwikis are displayed as an embedded iframe. Under Node.js Google's Puppeteer is used to load the innerwikis as off-screen web pages and then snapshot them as a PNG image.

Warnings

The <$innerwiki> widget is relatively slow and resource intensive: each time it is refreshed it will entirely rebuild the iframe containing the innerwiki.

The <$innerwiki> widget does not automatically resize with its container (for example, try hiding the sidebar in this wiki).

Prequisites

In order to take screenshots under Node.js, Google Puppeteer must first be installed from npm. For most situations, it should be installed at the root of the TiddlyWiki 5 repo:

cd Jermolene/TiddlyWiki5
npm install puppeteer

However, if you're working in a different repo that uses npm to install TiddlyWiki 5 then you should install Puppeteer into the same repo. The general rule is that the node_modules folder containing Puppeteer should be contained within an ancestor of the folder containing TiddlyWiki's tiddlywiki.js file.

Browser

The innerwiki widget specifies the dimensions of the virtual screen used to render the wiki (in pixels) and CSS styles to apply to it. Nested <$data> widgets are used to specify individual payload tiddlers to be loaded into the wiki. In this example, we initialise the innerwiki with two tiddlers "HelloThere" and "$:/DefaultTiddlers":

<$innerwiki width="1200" height="400" style="width:100%;" filename="screenshot-1.png">
	<$data title="HelloThere" text="This tiddler is inside a wiki"/>
	<$data title="$:/DefaultTiddlers" text="HelloThere"/>
</$innerwiki>

Renders as:

Note that the "screenshot" is a shrunken but fully interactive TiddlyWiki.

Node.js

To render these examples as a PNG bitmap under Node.js, execute the following at the command prompt:

tiddlywiki editions/innerwikidemo --screenshot $:/plugins/tiddlywiki/innerwiki/examples

The screenshots will be saved as screenshot-1.png etc in the ./output folder of the wiki.

To render this example tiddler as a static HTML file that embeds the screenshot images and includes the SVG overlays:

tiddlywiki editions/innerwikidemo --render '[[$:/plugins/tiddlywiki/innerwiki/examples]]' "examples.html" --build index

SVG overlays

Any displayable content within innerwiki widget is displayed within an automatically created SVG element. This allows overlays to be added:

<$innerwiki width="1200" height="400" style="width:100%;" filename="screenshot-2.png">
	<$data title="HelloThere" text="This tiddler is inside a wiki"/>
	<$data title="$:/DefaultTiddlers" text="HelloThere"/>
	<circle cx="600" cy="50" r="40" stroke="black" stroke-width="2" fill="green" />
	<<big-arrow 600 50>>
</$innerwiki>

Renders as:

Notice how macros can be used to encapsulate SVG fragments (see the source of this tiddler).

Clipping

A clipping rectangle can be applied to limit the area of the wiki that is displayed. For example:

<$innerwiki width="1200" height="400" style="width:100%;" clipLeft="500" clipTop="100" clipWidth="600" clipHeight="300" filename="screenshot-3.png">
	<$data title="HelloThere" text="! This tiddler is inside a wiki that is inside a wiki"/>
	<$data title="$:/DefaultTiddlers" text="HelloThere"/>
</$innerwiki>

Renders as:

Transcluding payload tiddlers

This example shows how the <$data> widget can be transcluded from other tiddlers (see $:/plugins/tiddlywiki/innerwiki/example-data):

<$innerwiki width="600" height="400" style="width:100%;" filename="screenshot-4.png">
	{{$:/plugins/tiddlywiki/innerwiki/example-data}}
	<$data title="HelloThere" text="! This tiddler is inside a wiki that is inside a wiki"/>
	<$data title="$:/DefaultTiddlers" text="HelloThere"/>
</$innerwiki>

Renders as:

Customising the wiki state

By injecting the right payload tiddlers, the innerwiki can be initialised to any desired state. In this example we inject a configuration tiddler to make the "more" page control button visible, and a state tiddler to cause the dropdown to appear:

<$innerwiki template="$:/plugins/tiddlywiki/innerwiki/template" filename="screenshot-5.png" width="1200" height="400" style="width:100%;">
	<$data title="HelloThere" text="! This tiddler is inside a wiki that is inside a wiki"/>
	<$data title="$:/DefaultTiddlers" text="HelloThere"/>
	<$data title="$:/config/PageControlButtons/Visibility/$:/core/ui/Buttons/more-page-actions" text="show"/>
	<$data title="$:/state/popup/more--1600698846" text="(151,144,21,25)"/>
</$innerwiki>

Renders as:

<$innerwiki template="$:/plugins/tiddlywiki/innerwiki/template" filename="screenshot-6.png" width="1200" height="400" style="width:100%;">
	<$data title="HelloThere" text="! This tiddler is inside a wiki that is inside a wiki"/>
	<$data title="Draft of 'HelloThere'" text="This tiddler is inside a wiki that is inside a wiki" draft.of="HelloThere" draft.title="HelloThere"/>
	<$data title="$:/DefaultTiddlers" text="[[Draft of 'HelloThere']]"/>
	<$data title="$:/state/sidebar" text="no"/>
	<$data title="$:/state/showeditpreview" text="yes"/>
</$innerwiki>

Renders as:

Draggable anchors

This example shows how the <$anchor> widget is used to display draggable anchors overlaid on the innerwiki. The <$anchor> widget is used to declare the tiddlers containing the coordinates of each anchor. These tiddlers can then be transcluded by SVG graphic primitives to position them according to the anchor locations.

screenshot-7-anchor-1-x: <$edit-text tag="input" tiddler="screenshot-7-anchor-1-x"/>

screenshot-7-anchor-1-y: <$edit-text tag="input" tiddler="screenshot-7-anchor-1-y"/>

screenshot-7-anchor-2-x: <$edit-text tag="input" tiddler="screenshot-7-anchor-2-x"/>

screenshot-7-anchor-2-y: <$edit-text tag="input" tiddler="screenshot-7-anchor-2-y"/>

<$innerwiki template="$:/plugins/tiddlywiki/innerwiki/template" filename="screenshot-7.png" width="1200" height="400" style="width:100%;">
	<$anchor x="screenshot-7-anchor-1-x" y="screenshot-7-anchor-1-y"/>
	<$anchor x="screenshot-7-anchor-2-x" y="screenshot-7-anchor-2-y"/>
	<$data title="HelloThere" text="! This tiddler is inside a wiki that is inside a wiki"/>
	<$data title="$:/DefaultTiddlers" text="HelloThere"/>
	<$macrocall $name="big-arrow" x={{screenshot-7-anchor-1-x}} y={{screenshot-7-anchor-1-y}}/>
	<circle cx={{screenshot-7-anchor-2-x}} cy={{screenshot-7-anchor-2-y}} r="50" stroke="blue" stroke-width="2" fill="green" />
</$innerwiki>

Renders as:

screenshot-7-anchor-1-x:

screenshot-7-anchor-1-y:

screenshot-7-anchor-2-x:

screenshot-7-anchor-2-y:

Inception

An innerwiki can itself contain an inner-innerwiki:

<$innerwiki width="1200" height="600" style="width:100%;" filename="screenshot-8.png">
	<$data title="HelloThere" text="! This tiddler is inside a wiki that is inside a wiki"/>
	<$data title="$:/DefaultTiddlers" text="HelloThere $:/plugins/tiddlywiki/innerwiki/inner-example"/>
	<$data $tiddler="$:/plugins/tiddlywiki/innerwiki"/>
	<<big-arrow 100 50 colour:#00ff00>>
</$innerwiki>

Renders as:

(You can see the innerwiki here: $:/plugins/tiddlywiki/innerwiki/inner-example)

Note the way that the innerwiki plugin has to be explicitly added to the innerwiki.

<$innerwiki> widget

The <$innerwiki> widget encapsulates an embedded wiki. It starts as a blank copy of the current wiki and can have additional payload tiddlers added via embedded <$data> widgets (see below).

It supports the following attributes:

<$data> widget

The <$data> widget is used within the <$innerwiki> widget to specify payload tiddlers to be added to the innerwiki.

It supports the following attributes:

It can be used in three different ways:

• Without the $tiddler or $filter attributes, the remaining attributes provide the fields for a single payload tiddler
• With the $tiddler attribute present, the payload tiddler takes its fields from that tiddler with the remaining attributes overriding those fields
• With the $filter attribute present, the payload is a copy of all of the tiddlers identified by the filter, with the remaining attributes overriding those fields of each one

This example injects a copy of the "HelloThere" tiddler with the addition of the field "custom" set to "Alpha":

<$data $tiddler="HelloThere" custom="Alpha"/>

This example injects all image tiddlers with the addition of the field "custom" set to "Beta":

<$data $filter="[is[image]]" custom="Beta"/>

<$anchor> widget

The <$anchor> widget is used within the <$innerwiki> widget to specify draggable anchors to be overlaid on the innerwiki.

It supports the following attributes:

This example declares an anchor whose coordinates are contained in the tiddlers my-anchor-x and my-anchor-y:

<$anchor x="my-anchor-x" y="my-anchor-y"/>

screenshot command

Saves PNG screenshots of the <$innerwiki> widgets rendered by a set of tiddlers identified by a filter.

--screenshot <filter> <deviceScaleFactor>

• filter: a filter identifying the tiddlers to be rendered, from which the individual <$innerwiki> widgets are screenshotted
• deviceScaleFactor: a scale factor for the screenshot (optional; defaults to 1)

A deviceScaleFactor of 4 or 5 gives high quality screenshots suitable for print use.