From 42f7c038244fa30ad320770f279e96f6d404b3cb Mon Sep 17 00:00:00 2001
From: Mario Pietsch <pmariojo@gmail.com>
Date: Tue, 27 Nov 2018 19:43:25 +0100
Subject: [PATCH] tm-open-external-window plus documentation. (#2721)

* first try - tm-open-external-window plus documentation.

* render examples and make help link a global variable
---
 core/modules/startup/story.js                 | 13 ++++++-
 ...WidgetMessage_ tm-open-external-window.tid | 39 +++++++++++++++++++
 2 files changed, 51 insertions(+), 1 deletion(-)
 create mode 100644 editions/tw5.com/tiddlers/messages/WidgetMessage_ tm-open-external-window.tid

diff --git a/core/modules/startup/story.js b/core/modules/startup/story.js
index 116dc6d2c..b71bc0439 100644
--- a/core/modules/startup/story.js
+++ b/core/modules/startup/story.js
@@ -31,6 +31,9 @@ var CONFIG_PERMALINKVIEW_COPY_TO_CLIPBOARD = "$:/config/Navigation/Permalinkview
 var CONFIG_PERMALINKVIEW_UPDATE_ADDRESS_BAR = "$:/config/Navigation/Permalinkview/UpdateAddressBar"; // Can be "yes" (default) or "no"
 
 
+// Links to help, if there is no param
+var HELP_OPEN_EXTERNAL_WINDOW = "http://tiddlywiki.com/#WidgetMessage%3A%20tm-open-external-window";
+
 exports.startup = function() {
 	// Open startup tiddlers
 	openStartupTiddlers();
@@ -56,6 +59,14 @@ exports.startup = function() {
 		$tw.rootWidget.addEventListener("tm-browser-refresh",function(event) {
 			window.location.reload(true);
 		});
+		// Listen for tm-open-external-window message
+		$tw.rootWidget.addEventListener("tm-open-external-window",function(event) {
+			var paramObject = event.paramObject || {},
+				strUrl = event.param || HELP_OPEN_EXTERNAL_WINDOW,
+				strWindowName = paramObject.windowName,
+				strWindowFeatures = paramObject.windowFeatures;
+			window.open(strUrl, strWindowName, strWindowFeatures);
+		});
 		// Listen for the tm-print message
 		$tw.rootWidget.addEventListener("tm-print",function(event) {
 			(event.event.view || window).print();
@@ -69,7 +80,7 @@ exports.startup = function() {
 			storyList = $tw.hooks.invokeHook("th-opening-default-tiddlers-list",storyList);
 			$tw.wiki.addTiddler({title: DEFAULT_STORY_TITLE, text: "", list: storyList},$tw.wiki.getModificationFields());
 			if(storyList[0]) {
-				$tw.wiki.addToHistory(storyList[0]);				
+				$tw.wiki.addToHistory(storyList[0]);
 			}
 		});
 		// Listen for the tm-permalink message
diff --git a/editions/tw5.com/tiddlers/messages/WidgetMessage_ tm-open-external-window.tid b/editions/tw5.com/tiddlers/messages/WidgetMessage_ tm-open-external-window.tid
new file mode 100644
index 000000000..994d5d787
--- /dev/null
+++ b/editions/tw5.com/tiddlers/messages/WidgetMessage_ tm-open-external-window.tid	
@@ -0,0 +1,39 @@
+caption: tm-open-external-window
+created: 201701211823
+modified: 201701211825
+tags: Messages
+title: WidgetMessage: tm-open-external-window
+type: text/vnd.tiddlywiki
+
+<<.from-version "5.1.14">>
+
+The `tm-open-external-window` message opens an external link eg: "http://tiddlywiki.com" in a new //browser// window. If no parameters are specified, it opens the help tiddler. Any additional parameters passed via the <<.param "paramObject">> are being provided as variables to the new window.
+
+|!Name |!Description |
+|param |URL of the tiddler to be opened in a new browser window, defaults to the [[TiddlyWiki help|http://tiddlywiki.com/#WidgetMessage%3A%20tm-open-external-window if empty]] |
+|paramObject |Optional: Hashmap of variables that will be provided to the window. see below |
+
+''parmObject''
+
+|!Name |!Description|!Important|
+|windowName|If a parameter is provided it can be used to open different links in the same window eg: `_tiddlywiki`. Default is empty, so every link opens a new window.|The behaviour is influenced by user settings in the browser and the browsers default behavior! |
+|windowFeatures|This parameter needs to be provided as a single string. eg: `"height=400, width=600"`. For detailed description about possible parameters see: [[Mozilla Help|https://developer.mozilla.org/en-US/docs/Web/API/Window/open#Window_features]] ||
+
+The `tm-open-external-window` message is usually generated with the ButtonWidget or ActionSendMessageWidget and is handled by the core itself.
+
+''Examples''
+
+<$macrocall $name='wikitext-example-without-html'
+src='<$button>
+<$action-sendmessage $message="tm-open-external-window" $param="http://tiddlywiki.com" windowName="_tiddlywiki" windowFeatures="height=500, width=900"/>
+Open ~TiddlyWiki - Action
+</$button>
+
+<$button>
+<$action-sendmessage $message="tm-open-external-window" $param="https://developer.mozilla.org/en-US/docs/Web/API/Window/open" windowName="_tiddlywiki" windowFeatures="height=400, width=600"/>
+Open Mozilla Help - Action
+</$button>
+
+<$button message="tm-open-external-window" param="http://tiddlywiki.com" >
+Open ~TiddlyWiki - Button
+</$button>'/>
\ No newline at end of file