From fc79db53abaca9719fb66777a6b5f8902df7e798 Mon Sep 17 00:00:00 2001
From: Jeremy Ruston <jeremy@osmosoft.com>
Date: Mon, 4 Mar 2013 11:13:10 +0000
Subject: [PATCH] Allow templating with the link widget

And add some documentation
---
 core/modules/rendertree/renderers/element.js  | 14 +++++++
 core/modules/widgets/link.js                  | 26 +++++--------
 .../tw5.com/tiddlers/widgets/LinkWidget.tid   | 37 +++++++++++++++++++
 3 files changed, 60 insertions(+), 17 deletions(-)
 create mode 100644 editions/tw5.com/tiddlers/widgets/LinkWidget.tid

diff --git a/core/modules/rendertree/renderers/element.js b/core/modules/rendertree/renderers/element.js
index bfb53df8d..ac79e31f7 100644
--- a/core/modules/rendertree/renderers/element.js
+++ b/core/modules/rendertree/renderers/element.js
@@ -269,6 +269,20 @@ ElementRenderer.prototype.getContextScopeId = function() {
 	return guidBits.join("");
 };
 
+/*
+Find a named macro definition
+*/
+ElementRenderer.prototype.findMacroDefinition = function(name) {
+	var context = this.renderContext;
+	while(context) {
+		if(context.macroDefinitions && context.macroDefinitions[name]) {
+			return context.macroDefinitions[name];
+		}
+		context = context.parentContext;
+	}
+	return undefined;
+};
+
 exports.element = ElementRenderer
 
 })();
diff --git a/core/modules/widgets/link.js b/core/modules/widgets/link.js
index 157f8896e..c342ec790 100644
--- a/core/modules/widgets/link.js
+++ b/core/modules/widgets/link.js
@@ -28,7 +28,6 @@ LinkWidget.prototype.generate = function() {
 	// Get the parameters from the attributes
 	this.to = this.renderer.getAttribute("to");
 	this.hover = this.renderer.getAttribute("hover");
-	this.qualifyHoverTitle = this.renderer.getAttribute("qualifyHoverTitle");
 	// Determine the default link characteristics
 	this.isExternal = isLinkExternal(this.to);
 	if(!this.isExternal) {
@@ -52,15 +51,22 @@ LinkWidget.prototype.generate = function() {
 		events.push({name: "mouseout", handlerObject: this, handlerMethod: "handleMouseOverOrOutEvent"});
 	}
 	// Get the value of the tw-wikilinks configuration macro
-	var wikiLinksMacro = this.findMacroDefinition("tw-wikilinks"),
+	var wikiLinksMacro = this.renderer.findMacroDefinition("tw-wikilinks"),
 		useWikiLinks = wikiLinksMacro ? !(wikiLinksMacro.text.trim() === "no") : true;
 	// Set up the element
 	if(useWikiLinks) {
 		this.tag = "a";
 		this.attributes = {
-			href: this.isExternal ? this.to : encodeURIComponent(this.to),
 			"class": classes.join(" ")
 		};
+		if(this.isExternal) {
+			this.attributes.href = this.to;
+		} else {
+			var wikiLinkTemplateMacro = this.renderer.findMacroDefinition("tw-wikilink-template"),
+				wikiLinkTemplate = wikiLinkTemplateMacro ? wikiLinkTemplateMacro.text.trim() : "$uri_encoded$",
+				wikiLinkText = wikiLinkTemplate.replace("$uri_encoded$",encodeURIComponent(this.to));
+			this.attributes.href = wikiLinkText;
+		}
 	} else {
 		this.tag = "span";
 	}
@@ -117,20 +123,6 @@ LinkWidget.prototype.refreshInDom = function(changedAttributes,changedTiddlers)
 	}
 };
 
-/*
-Find a named macro definition
-*/
-LinkWidget.prototype.findMacroDefinition = function(name) {
-	var context = this.renderer.renderContext;
-	while(context) {
-		if(context.macroDefinitions && context.macroDefinitions[name]) {
-			return context.macroDefinitions[name];
-		}
-		context = context.parentContext;
-	}
-	return undefined;
-};
-
 exports.link = LinkWidget;
 
 })();
diff --git a/editions/tw5.com/tiddlers/widgets/LinkWidget.tid b/editions/tw5.com/tiddlers/widgets/LinkWidget.tid
new file mode 100644
index 000000000..d8d3ff3cf
--- /dev/null
+++ b/editions/tw5.com/tiddlers/widgets/LinkWidget.tid
@@ -0,0 +1,37 @@
+title: LinkWidget
+tags: docs widget
+
+The `link` widget generates links to tiddlers and external URIs.
+
+! Attributes
+
+* ```to``` - link target can be a URL 
+* ```hover``` - the title of a tiddler to display when hovering over the link
+
+! CSS Classes
+
+* ```tw-tiddlylink``` - applied to all links
+* ```tw-tiddlylink-external``` - applied to external, non-tiddler links
+* ```tw-tiddlylink-internal``` - applied to tiddler links
+* ```tw-tiddlylink-missing``` - applied to tiddler links where the target tiddler doesn't exist
+* ```tw-tiddlylink-resolves``` - applied to tiddler links when the target tiddler does exist
+
+! Configuration macros
+
+Configuration macros can be used to modify the behaviour of the link widget.
+
+!! tw-wikilinks
+
+Links are suppressed if the macro `tw-wikilinks` evaluates to the string `no`. For example:
+
+```
+\define tw-wikilinks() no
+```
+
+!! tw-wikilink-template
+
+Link targets default to the URL encoded title of the tiddler. The `href` can be templated by defining the configuration macro `tw-wikilink-template`, and including within it the token `$uri_encoded$`. For example:
+
+```
+\define tw-wikilink-template() http://tiddlywiki.com/#$uri_encoded$
+```