DOC-1820: Menu Toolbar Button Docs page restructuring

modules/ROOT/examples/live-demos/custom-toolbar-menu-button-search/index.js

@@ -1,53 +1,38 @@
 tinymce.init({
   selector: 'textarea#custom-toolbar-menu-button-search',
   height: 500,
-  toolbar: 'mybutton',
-
+  toolbar: 'searchMenuButton',
   setup: (editor) => {
-    /* Menu items are recreated when the menu is closed and opened, so we need
-       a variable to store the toggle menu item state. */
     let toggleState = false;
-
-    /* example, adding a toolbar menu button */
-    editor.ui.registry.addMenuButton('mybutton', {
-      text: 'My searchable button',
-      search: {
-        placeholder: 'Type...'
-      },
+    editor.ui.registry.addMenuButton('searchMenuButton', {
+      text: 'Searchable Menu',
+      search: { placeholder: 'Search items...' },
       fetch: (callback, fetchContext) => {
-        if (fetchContext.pattern.length > 0) {
-          callback([
-            {
-              type: 'menuitem',
-              text: `You searched for: "${fetchContext.pattern}"`,
-              onAction: () => editor.insertContent(`<strong>Inserted selected search result</strong>`)
-            }
-          ]);
-        } else {
-          const items = [
-            {
-              type: 'menuitem',
-              text: 'Menu item 1',
-              onAction: () => editor.insertContent('&nbsp;<em>You clicked menu item 1!</em>')
+        // Define a list of all menu items
+        const allItems = [
+          { type: 'menuitem', text: 'Apple', onAction: () => editor.insertContent('Apple') },
+          { type: 'menuitem', text: 'Banana', onAction: () => editor.insertContent('Banana') },
+          { type: 'togglemenuitem', text: 'Toggleable Menu', onAction: () => { 
+            toggleState = !toggleState;
+            editor.insertContent('Toggleable Menu'); 
             },
-            {
-              type: 'togglemenuitem',
-              text: 'Toggle menu item',
-              onAction: () => {
-                toggleState = !toggleState;
-                editor.insertContent('&nbsp;<em>You toggled a menuitem ' + (toggleState ? 'on' : 'off') + '</em>');
-              },
-              onSetup: (api) => {
-                api.setActive(toggleState);
-                return () => {};
-              }
-            }
-          ];
-          callback(items);
-        }
+            onSetup: (api) => {
+              api.setActive(toggleState);
+              return () => {};
+            },
+          },
+        ];
+
+        // Use the `pattern` to filter items
+        const filteredItems = allItems.filter(item =>
+          item.text.toLowerCase().includes(fetchContext.pattern.toLowerCase())
+        );
+
+        // Pass the filtered list to the callback
+        callback(filteredItems);
       }
     });
-
   },
+
   content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
 });

modules/ROOT/pages/custom-menu-toolbar-button.adoc

@@ -37,25 +37,30 @@ include::partial$misc/admon-requires-6.4v.adoc[]
 |setIcon |`+(icon: string) => void+` |Sets the icon of the button.
 |===
 
-== Menu button example and explanation
+== Menu button example and explanation without search enabled
 
 The following is a simple toolbar menu button example:
 
 liveDemo::custom-toolbar-menu-button[tab="js"]
 
-This example configures a toolbar menu button with the label `+My Button+` that opens the specified menu when clicked. The top-level menu contains two items. The first menu item inserts content when clicked and the second menu item opens a submenu containing two menu items which insert content when clicked.
+This example configures a toolbar menu button labeled `+My Button+` that opens a menu when clicked. The menu contains two items: one that inserts content and another that opens a submenu with two additional items to be inserted when clicked.
 
-The `+fetch+` function is called when the toolbar menu button's menu is opened. It is a function that takes a callback and passes it an array of menu items to be rendered in the drop-down menu. This allows for asynchronous fetching of the menu items.
+The `+fetch+` function retrieves an array of menu items and passes it to the callback, which renders them in the dropdown menu. This enables asynchronous menu generation. 
 
 [[searchable-menu-buttons]]
-== Searchable menu buttons
+== Fetch with Searchable menu buttons 
 
 include::partial$misc/admon-requires-6.2v.adoc[]
 
-The button's menu can be configured to have an input field for searching, as well as its usual items. The presence of the input field is controlled by the `+search+` field in the xref:options[options]. The `+search+` field can be a `+boolean+` or an `+object+` containing a single optional string `placeholder`. By default, `+search+` is false. If `+search+` is not false, the button's menu will contain an input field with any specified placeholder text. As the user types into this field, the `+fetch+` function will be called with the text in the input field passed back as part of `+fetchContext+`. The `+fetch+` function is responsible for using this `+fetchContext+` to determine which items to pass to its `+success+` callback.
+The button's menu can include a search input field alongside it's items, controlled by the `+search+` option. The  `+search+` option can be either:
 
-The `+fetchContext+` is an object containing a single string property: `+pattern+`. If the toolbar menu button has not configured `search` to be active, then the `+pattern+` string will be empty.
+* A `+boolean+` value: When `true`, it enables the search field. The text inside the field is empty.
 
+* An `+object+`: Allows customization with a placeholder to set placeholder text for the input field. 
+
+By default, `+search+` is false, meaning no search field is displayed. When enabled, the search field allows for dynamic updating of the menu content based on their input. The `+fetchContext+` object provides additional information to the `+fetch+` function which can be used to determine the menu's behaviour or content.
+
+When `+search+` is enabled, depending on the `+pattern+` property of `+fetchContext+` different menu buttons options will be shown. This is because when a new keypress is added to the `+search+`, `+fetch+` is called to update the possible options from the search.
 == Searchable menu button example and explanation
 
 include::partial$misc/admon-requires-6.2v.adoc[]
@@ -64,8 +69,8 @@ The following is a simple toolbar menu button example, where searching has been
 
 liveDemo::custom-toolbar-menu-button-search[tab="js"]
 
-This example configures a toolbar menu button with the label `+My searchable button+` that opens the specified menu when clicked. The menu will contain a search input field because `+search+` is not `+false+`. The input field's https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#placeholder[placeholder attribute] will be `+Type...+`.
+This example configures a toolbar menu button with the label `+Searchable Menu+` that opens the specified menu when clicked. The menu will contain a search input field because `+search+` is not `+false+`. The `+fetch+` function is called with a `+pattern+` being "Search items...". The `+fetchContext+` is set to the `+pattern+` and as `+pattern+` is updated the menu will update. When searching the `+pattern+` is filtered and when the pattern doesn't meet the menuitems the search closes.
 
-Initially, when the menu opens, the search input field will be empty, and the `+fetch+` function is called with an empty `+pattern+` for its `+fetchContext+`. In that situation, `+fetch+` passes back an array of two items to be rendered in the drop-down menu. When the user types in the input field, `+fetch+` will be called again, except this time, the `+pattern+` property in `+fetchContext+` will reflect the value typed in the input field. For illustration purposes, this example then passes back an item that contains this pattern inside the item's text. In a more real-life example, the `+pattern+` could be used to filter which of the items are passed to the callback.
+The input field's https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#placeholder[placeholder attribute] will be `+Type...+`.
 
 include::partial$misc/onSetup.adoc[]