transcludeTid.js

transcludeTid.js

/*
This is a Tiddly Wiki https://tiddlywiki.com/ widget. 
Tested with v5.4.0 and TiddlyWikiWatcher https://github.com/MircoBabin/TiddlyWikiWatcher v2.5.

transcludeTid version: 1.0

Usage:
<$transcludeTid $url="./my-tids/saved.tid" />

This widget transcludes (embeds) the relative TID url/file "./my-tids/saved.tid". 
A .tid file can be obtained via the menu "export tiddler" / "TID text file" of any tiddler.

---
Installation:

1) Open your Tiddly Wiki. For example with https://github.com/MircoBabin/TiddlyWikiWatcher
2) Create a new Tiddler titled "transcludeTid.js".
3) Paste this source in the body.
4) Set content type to "application/javascript".
5) Add field "module-type" with value "widget".
6) Save tiddler.
7) Save Tiddly Wiki and close and reopen the Tiddly Wiki.

---
Changelog:

2026-06-10: initial version 1.0

---
MIT license 

Copyright (c) 2026 Mirco Babin

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
*/

"use strict";

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

var TranscludeTidWidget = function(parseTreeNode,options) {
	this.initialise(parseTreeNode,options);
};

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

/*
Render this widget into the DOM
*/
TranscludeTidWidget.prototype.render = function(parent,nextSibling) {
    this.parentDomNode = parent;
    this.computeAttributes({asList: true});
    var url = this.getAttribute("$url");
    var tempTiddlerName = this.executeMakeTempTiddlerName(url);

    var found = this.wiki.getTiddler(tempTiddlerName);
    if (found) {
        this.executeTransclude(tempTiddlerName, parent,nextSibling);
        return;
    }

	var self = this;
	$tw.utils.httpRequest({
		url: url,
		type: "GET",
		callback: function(err,data) {
			if(!err) {
				var tiddlers = self.wiki.deserializeTiddlers(".tid",data,self.wiki.getCreationFields());
                var tiddler = (tiddlers.length === 1 ? tiddlers[0] : null);
                if (tiddler !== null) {
                    tiddler["title"] = tempTiddlerName;
					self.wiki.addTiddlers([tiddler]); // triggers refresh()
				}
			}
		}
	});
};

TranscludeTidWidget.prototype.executeMakeTempTiddlerName = function(url) {
    if (!this.transcludeTid_tempTiddlerName) {
        this.transcludeTid_tempTiddlerName = '$:/temp/transcludeTid-';
        // url => utf-8 => hex
        this.transcludeTid_tempTiddlerName += Array.from(
            new TextEncoder().encode(url),
            byte => byte.toString(16).padStart(2, "0")
        ).join("");
    }

    return this.transcludeTid_tempTiddlerName;
}

TranscludeTidWidget.prototype.executeTransclude = function(tiddlerTitle, parent,nextSibling) {
    var myWikitext = '<$transclude $tiddler="' + tiddlerTitle + '" $mode="block" />';
    var parser = this.wiki.parseText("text/vnd.tiddlywiki", myWikitext);
    
    this.makeChildWidgets(parser.tree);
    this.renderChildren(parent,nextSibling);
};

/*
Selectively refreshes the widget if needed. Returns true if the widget or any of its children needed re-rendering
*/
TranscludeTidWidget.prototype.refresh = function(changedTiddlers) {
    if (!changedTiddlers[this.transcludeTid_tempTiddlerName] || 
        !changedTiddlers[this.transcludeTid_tempTiddlerName].modified) {
        return false;
    }

    this.refreshSelf();
    return true;
};

exports.transcludeTid = TranscludeTidWidget;

The _canonical_uri field in combination with the ExternalText system does not work. When _canonical_uri is set to ./my-tids/saved.tid, the end-result is that saved.tid is imported, it is not transcluded. And Tiddly Wiki will show it is changed because of the import, while nothing actually changed.

I wanted an external TID text file transcluded inside a tiddler. This external TID is shared/copied between multiple persons. Only one person is the author and edits the TID.

Created issue TiddlyWiki/TiddlyWiki5#9877