This tutorial is intended to demonstrate a few examples of when calls to the refresh method happen vs. when a widget is recreated from scratch.

This is accomplished with a refreshcount.js widget which sets a counter to zero when the widget is created and increments the counter every time the refresh method is called. Here is the full code:

/*\

widget to count the number of times this widget refreshes

\*/
(function() {

/*jslint node: true, browser: true */
/*global $tw: false */
"use strict";

var Widget = require("$:/core/modules/widgets/widget.js").widget;

var MyWidget = function(parseTreeNode, options) {
	this.refreshCount = 0;
	this.initialise(parseTreeNode, options);
};

/*
Inherit from the base widget class
*/
MyWidget.prototype = new Widget();

/*
Render this widget into the DOM
*/
MyWidget.prototype.render = function(parent, nextSibling) {
	this.parentDomNode = parent;
	var textNode = this.document.createTextNode(this.refreshCount + " refreshes");
	parent.insertBefore(textNode, nextSibling);
	this.domNodes.push(textNode);
};

MyWidget.prototype.refresh = function(changedTiddlers) {
	// Regenerate and rerender the widget and replace the existing DOM node
	this.refreshCount++;
	this.refreshSelf();
	return true;
};

exports.refreshcount = MyWidget;

})();

These are the key parts of the code from above:

this.refreshCount = 0;
this.document.createTextNode(this.refreshCount + " refreshes");
this.refreshCount++;

In the following example (see Widget refresh demo III for the code), two instances of the refreshcount widget are created. One at the top level and the other inside a list widget whose filter results depend on the value in the text field of the test widget. The tiddler store can be modified in a few ways via two buttons and an input box:

• Modify a different tiddler - every time this button is clicked, both counters increment, indicating the refresh method is being called
• Modify this tiddler - clicking this button modifies the tiddler itself. In earlier TiddlyWiki versions that caused both widgets to be recreated from scratch and the counters are thereby reset to zero. Since version 5.2.0 modifying another field in this tiddler does not cause the widgets to be recreated and the counters are not reset.
• Text field of tiddler='test' - typing text into the input box causes the counter in the standalone refreshcount widget to be incremented. But the other instance of the widget is embedded inside a list widget whose filter output depends on the value of the tiddler field which is being modified. This causes it to recreate its children from scratch and the counter is reset every time. So with every keystroke, the counter on the left is incremented, but the counter on the right goes to/stays at zero.