Add tag page events + developer documentation

It's now possible for other plugins to take over the job
of creating tag pages, or to detect when one has been
created and move, rename, or modify it.  See the Developer
Notes section of the README for details.

README.md

@@ -117,4 +117,52 @@ Let's say you have a tag named `#foo/bar` and you rename `#foo` to `#Bar/baz`.
 
 Rather, this kind of thing will happen if the `#Bar/baz` tag is the first tag beginning with some variant of `bar` that Obsidian encounters when generating the tag pane.  Obsidian just uses the first-encountered string of a particular case as the "display name" for the tag, and then counts all subsequent occurrences as the same tag.
 
-This is just how Obsidian tags work, and not something that Tag Wrangler can work around.  But you can easily fix the problem by renaming anything that's in the "wrong" case to the "right" case.  It just means that (as is already the case in Obsidian) you can't have more than one casing of the same tag name displayed in the tag pane, and that now you can easily rename tags to a consistent casing, if desired.
+This is just how Obsidian tags work, and not something that Tag Wrangler can work around.  But you can easily fix the problem by renaming anything that's in the "wrong" case to the "right" case.  It just means that (as is already the case in Obsidian) you can't have more than one casing of the same tag name displayed in the tag pane, and that now you can easily rename tags to a consistent casing, if desired.
+
+
+
+## Developer Notes
+
+Tag Wrangler triggers the following events on the `app.workspace` that may be useful for integration with other plugins:
+
+### `tag-wrangler:contextmenu`
+
+This event allows other plugins to add menu items to the Tag Wrangler context menus.  You can register a callback like this:
+
+```typescript
+type menuInfo = {
+  query?: string           // the current global search query
+  isHierarchy: boolean     // true if the tag is a child tag in the tag pane (sorted by hierarchy)
+  tagPage: TFile|undefined // the tag page for the note, if it exists
+};
+
+this.registerEvent(
+  app.workspace.on("tag-wrangler:contextmenu", (menu: Menu, tagName: string, info: menuInfo) => {
+    // add items to menu here
+  })
+);
+```
+
+### `tag-page:will-create`
+
+This event allows other plugins to take over creation of tag pages.  You can register a callback like so:
+
+```typescript
+type tagPageEvent = {
+  tag: string
+  file?: TFile
+}
+
+this.registerEvent(app.workspace.on("tag-page:will-create", (evt: tagPageEvent) => {
+  if (!evt.file) {
+    // create the file here, then save it in the event
+    evt.file = // the new file to use
+  }
+}));
+```
+
+Note that if `evt.file` exists, your callback should not do anything, as the file has already been created.  If you want to modify an already-created tag page file, use the `tag-page:did-create` event instead.  (See below.)
+
+### `tag-page:did-create`
+
+This event allows other plugins to modify or rename a newly-created tag page.  It has the same callback signature as `tag-page:will-create`, except the `file` field will always contain a file.  (The one created by Tag Wrangler or by a callback to `tag-page:will-create`.)  You should use the `app.vault.process()` method to do any changes, to prevent accidental file overwrites and data loss.  (It should also be safe to `app.vault.rename()` it to change its name or location.)

manifest.json

@@ -3,7 +3,7 @@
   "name": "Tag Wrangler",
   "author": "PJ Eby",
   "authorUrl": "https://github.com/pjeby",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "minAppVersion": "0.15.9",
   "description": "Rename, merge, toggle, and search tags from the tag pane",
   "isDesktopOnly": false

src/plugin.js

@@ -27,15 +27,23 @@ export default class TagWrangler extends Plugin {
     }
 
     async createTagPage(tagName, newLeaf) {
-        const baseName = new Tag(tagName).name.split("/").join(" ");
-        const folder = this.app.fileManager.getNewFileParent(this.app.workspace.getActiveFile()?.path || "");
-        const path = this.app.vault.getAvailablePath(folder.getParentPrefix()+baseName, "md");
-        this.openTagPage(await this.app.vault.create(path, [
-            "---",
-            `Aliases: [ ${JSON.stringify(Tag.toTag(tagName))} ]`,
-            "---",
-            ""
-        ].join("\n")), true, newLeaf);
+        const tag = new Tag(tagName);
+        const tp_evt = { tag: tag.canonical, file: undefined };
+        app.workspace.trigger("tag-page:will-create", tp_evt);
+        if (!tp_evt.file) {
+            const baseName = new Tag(tagName).name.split("/").join(" ");
+            const folder = this.app.fileManager.getNewFileParent(this.app.workspace.getActiveFile()?.path || "");
+            const path = this.app.vault.getAvailablePath(folder.getParentPrefix()+baseName, "md");
+            const file = await this.app.vault.create(path, [
+                "---",
+                `Aliases: [ ${JSON.stringify(Tag.toTag(tagName))} ]`,
+                "---",
+                ""
+            ].join("\n"));
+            tp_evt.file = file;
+        }
+        app.workspace.trigger("tag-page:did-create", tp_evt);
+        this.openTagPage(tp_evt.file, true, newLeaf);
     }
 
     async onload(){
@@ -279,7 +287,7 @@ class TagPageUIHandler extends Component {
                 if (!Keymap.isModEvent(event) && !altKey) return;
                 const tagName = toTag(targetEl), tp = tagName && this.plugin.tagPage(tagName);
                 if (tp) {
-                    this.plugin.openTagPage(tp, false, !altKey);
+                    this.plugin.openTagPage(tp, false, Keymap.isModEvent(event));
                     event.preventDefault();
                     event.stopPropagation();
                     return false;

versions.json

@@ -1,5 +1,5 @@
 {
-    "0.5.8": "0.15.9",
+    "0.5.9": "0.15.9",
     "0.5.5": "0.15.9",
     "0.5.3": "0.14.5",
     "0.5.2": "0.13.19",