From: Dan Brown <redacted>
Date: Thu, 4 May 2023 16:42:38 +0000 (+0100)
Subject: Done review pass of #4, mainly updated comments/wording
X-Git-Url: http://source.bookstackapp.com/hacks/commitdiff_plain/2865dd844834494269e4f285ba9f28d659a85864

Done review pass of #4, mainly updated comments/wording
---

diff --git a/content/wysiwyg-autocompleter/head.html b/content/wysiwyg-autocompleter/head.html
index 4d9c68c..cdacb9a 100644
--- a/content/wysiwyg-autocompleter/head.html
+++ b/content/wysiwyg-autocompleter/head.html
@@ -1,22 +1,22 @@
 <script>
-    // Listen to the BookStack setup TinyMCE editor event to run custom actions against the editor instance.
+    // Listen to the BookStack setup TinyMCE editor event to run custom actions against the editor instance
     window.addEventListener('editor-tinymce::setup', event => {
-        // Gain a reference to the TinyMCE editor instance.
+        // Gain a reference to the TinyMCE editor instance
         const editor = event.detail.editor;
 
         // Register a custom cat svg icon
         editor.ui.registry.addIcon('insertcaticon', `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 72 72" fill="currentColor"><path d="M13.622 14.093c-.61-.007-1.013.055-1.15.2-.984 1.041 3.094 15.61 5.738 21.974a29.714 29.714 0 0 0-1.332 8.794 29.714 29.714 0 0 0 29.714 29.714 29.714 29.714 0 0 0 29.715-29.714 29.714 29.714 0 0 0-1.158-8.21c2.646-6.49 6.603-20.69 5.633-21.718-.886-.937-12.948 1.595-20.093 3.772a29.714 29.714 0 0 0-14.097-3.558 29.714 29.714 0 0 0-13.048 3.024c-5.932-1.906-16.39-4.24-19.922-4.278Zm6.678 6.139c2.817.03 11.16 1.892 15.891 3.412a23.703 23.703 0 0 1 10.408-2.413 23.703 23.703 0 0 1 11.245 2.839c5.7-1.736 15.321-3.756 16.027-3.009.775.82-2.382 12.147-4.493 17.324a23.703 23.703 0 0 1 .924 6.549A23.703 23.703 0 0 1 46.6 68.637a23.703 23.703 0 0 1-23.702-23.703 23.703 23.703 0 0 1 1.063-7.015c-2.11-5.076-5.362-16.697-4.578-17.528.11-.115.431-.165.918-.16z" transform="translate(-10.627 -8.434)"/></svg>`);
 
-        // add custom autocompleter
+        // Register a custom autocompleter
         editor.ui.registry.addAutocompleter('autocompleter-cat', {
-            ch: ':', // the trigger character to open the autocompleter
-            minChars: 2, // lower number means searching sooner - but more lookups as we go
-            columns: 1, // must be 1 for text-based results
+            ch: ':', // The trigger character to open the autocompleter
+            minChars: 1, // Number of entered characters to wait for before searching
+            columns: 1, // Result columns, generally will be 1 for text-based results
             fetch: function (pattern, maxResults, fetchOptions) {
-                // A function called when the autocompleter gets triggered, which gets passed 
+                // This function is called when the autocompleter gets triggered, which gets passed 
                 // the current matched text pattern, the maximum number of expected results and 
                 // any additional fetch options. 
-                // The function  should return a Promise containing matching results.
+                // The function should return a Promise containing matching results.
 
                 return Promise.resolve(
                     [
@@ -36,18 +36,15 @@
                 );
             },
             onAction: function (autocompleteApi, rng, value) {
-                // called when an item from the list is selected
-                // we still need to be the one who does the insert in to the editor
+                // This function is called when an item from the list is selected
 
-                // insert in to the editor
+                // Insert the selected item's value (HTML) into the editor
                 editor.selection.setRng(rng);
                 editor.insertContent(value);
             
-                // hide the autocompleter
+                // Hide the autocomplete UI
                 autocompleteApi.hide();
             }
         });
     });
-
-    
 </script>
diff --git a/content/wysiwyg-autocompleter/index.md b/content/wysiwyg-autocompleter/index.md
index 3f8ea96..a789bf4 100644
--- a/content/wysiwyg-autocompleter/index.md
+++ b/content/wysiwyg-autocompleter/index.md
@@ -1,25 +1,26 @@
 +++
-title = "WYSIWYG Editor Autocompleter"
+title = "WYSIWYG Editor Autocomplete Suggestions"
 author = "@razem-io"
-date = 2023-05-04T23:00:00Z
-updated = 2023-05-04T23:00:00Z
-tested = "v23.02"
+date = 2023-05-04T16:00:00Z
+updated = 2023-05-04T16:00:00Z
+tested = "v23.05"
 +++
 
-This hack adds custom autocompleter support to the WYSIWYG page editor (TinyMCE). An autocompleter displays suggestions while the user is typing. Suggestions are shown when the trigger character is entered after a space or at the start of a new line (such as ' :'). Pressing the Escape key will close the autocompleter.
+This hack adds custom autocomplete suggestions to the WYSIWYG page editor (TinyMCE). An autocomplete popup box will show after a "trigger character" (`:` as configured by default in this hack) is entered after a space, or at the start of a line. Pressing the Escape key will close the autocompleter.
 
-This hack provides significant examples of TinyMCE (The library used for the WYSIWYG) content manipulation and extension.
+By default, two autocomplete options are configured: `Cat 1` and `Cat 2`.
+Entering `:c` within the editor will show the autocomplete containing these two options.
+These options can be configured from line 21 in the code.
+
+This hack serves as a good example of registering autocomplete options with TinyMCE (The library used for the WYSIWYG).
 The code is heavily commented to assist as a helpful example.
-For significant alterations, you'll likely want to review the [TinyMCE documentation](https://www.tiny.cloud/docs/tinymce/6/autocompleter/)
-to understand the full set of available capabilities and actions within the TinyMCE editor API.
+You may want to review the [TinyMCE Autocompleter documentation](https://www.tiny.cloud/docs/tinymce/6/autocompleter/)
+to understand the full set of capabilities and options available.
 
 #### Considerations
 
 - This heavily relies on internal methods of TinyMCE, which may change upon any BookStack release as we update the editor libraries.
-- All logic is within the WYSIWYG editor, and therefore you won't get the same functionality via the API or other editors.
-- The syntax & code used likely won't be cross-compatible with the markdown editor.
-- This has been tested to some degree but there's a reasonable chance of bugs or side affects, since there's quite a lot going on here.
-- There's a lot of custom code here. You could instead put this code (without the HTML `<script>` tags) in an external JavaScript file and then just use a single `<script src="/https/source.bookstackapp.com/path/to/file.js"></script>` within the custom head setting.
+- All logic is within the WYSIWYG editor, and therefore you won't get the same functionality via other editors.
 
 #### Code