Add th-before-importing hook mechanism (#5464)

core/modules/widgets/navigator.js

@@ -557,10 +557,12 @@ NavigatorWidget.prototype.handleImportTiddlersEvent = function(event) {
 NavigatorWidget.prototype.handlePerformImportEvent = function(event) {
 	var self = this,
 		importTiddler = this.wiki.getTiddler(event.param),
-		importData = this.wiki.getTiddlerDataCached(event.param,{tiddlers: {}}),
+		importData,
 		importReport = [];
-	// Add the tiddlers to the store
 	importReport.push($tw.language.getString("Import/Imported/Hint") + "\n");
+	// If you need to modify the import tiddler payload then consider th-importing-tiddler instead
+	importTiddler = $tw.hooks.invokeHook("th-before-importing",importTiddler);
+	importData = this.wiki.getTiddlerDataCached(event.param,{tiddlers: {}}),
 	$tw.utils.each(importData.tiddlers,function(tiddlerFields) {
 		var title = tiddlerFields.title;
 		if(title && importTiddler && importTiddler.fields["selection-" + title] !== "unchecked") {
@@ -569,7 +571,10 @@ NavigatorWidget.prototype.handlePerformImportEvent = function(event) {
 			} else {
 				var tiddler = new $tw.Tiddler(tiddlerFields);
 			}
+			// th-importing-tiddler doesn't allow user interaction by default
+			// If you want to use the default UI then use: $:/core/modules/upgraders/ instead
 			tiddler = $tw.hooks.invokeHook("th-importing-tiddler",tiddler);
+			// Add the tiddlers to the store
 			self.wiki.addTiddler(tiddler);
 			importReport.push("# [[" + tiddler.fields.title + "]]");
 		}

editions/dev/tiddlers/new/Hook_ th-before-importing.tid

@@ -0,0 +1,68 @@
+created: 20210203184649726
+modified: 20210208152038746
+tags: HookMechanism
+title: Hook: th-before-importing
+type: text/vnd.tiddlywiki
+
+This hook allows plugins to inspect or modify the `importTiddler` object ''before'' any tiddlers are imported. It is invoked after the final "Import" button is clicked, but ''before'' the selected tiddlers are being imported into the store.
+
+''Intended Usecases'':
+
+* Manipulate the import "selection state"
+* Eg: create a customized "log-tiddler" that contains a heading, that should only be written once
+
+''Important'': 
+
+* This hook ''should not'' be used to manpulate the `importTiddler.fields.text` element!
+* If you want to give the users a possibility to verify the imported data, use ùpgraders like: `$:/core/modules/upgraders/` instead
+* If you need to manipulate the imported tiddler content, without default user interaction, consider: [[Hook: th-importing-tiddler]] instead
+
+The hook is part of the `NavigatorWidget.prototype.handlePerformImportEvent` function.
+
+Hook function parameters:
+
+* ''importTiddler'': an object, that contains information about "selected / unselected" tiddlers and more
+
+Return value:
+
+* ''importTiddler'': object
+
+The hook must return the `importTiddler` object. For many usecases the object will be returned unmodified.
+
+''Example code how to implement a hook in your project''
+
+```
+/*\
+title: $:/plugins/<author>/<plugin>/th-before-importing.js
+type: application/javascript
+module-type: startup
+
+YOUR DISCRCRIPTION COMES HERE!
+
+\*/
+(function(){
+
+/*jslint node: true, browser: true */
+/*global $tw: false, exports: true */
+"use strict";
+
+// Export name and synchronous status
+exports.name = "<yournamecomesherewithoutspaces>";
+exports.platforms = ["browser"];
+exports.after = ["startup"];
+exports.synchronous = true;
+
+// Define your variables here!
+
+exports.startup = function() {
+	$tw.hooks.addHook("th-before-importing",function(importTiddler) {
+
+// YOUR CODE !
+
+		return importTiddler;
+	});
+};
+
+})();
+
+```

editions/dev/tiddlers/new/Hook__th-importing-tiddler.tid

@@ -1,11 +1,13 @@
 created: 20170209130829546
-modified: 20171010115148355
+modified: 20210203190724491
 tags: HookMechanism
 title: Hook: th-importing-tiddler
 type: text/vnd.tiddlywiki
 
 This hook allows plugins to inspect or modify tiddlers as they are imported via the import mechanism. It is invoked when the final "Import" button is clicked, and the selected tiddlers are being imported into the store.
 
+The hook is part of the `NavigatorWidget.prototype.handlePerformImportEvent` function.
+
 Use this hook if you want to process each imported tiddler after they have been extracted from the files.  See [[Hook: th-importing-file]] if you want to control how tiddlers are extracted from files during an import.
 
 Hook function parameters: