From d2056003f91c36da09b8aed635e95cd53a4bf3f2 Mon Sep 17 00:00:00 2001 From: Diogo Goncalves Date: Fri, 25 Jun 2021 11:22:42 +1000 Subject: [PATCH] TINY-6587: Review Autocompleter, Split Button, and Menu Button page (#2000) --- _includes/components/choice-menu-items.md | 11 +---- .../index.html | 0 .../autocompleter-autocompleteitem/index.js | 48 +++++++++++++++++++ .../autocompleter-cardmenuitem/index.html | 4 ++ .../index.js | 26 +--------- ui-components/autocompleter.md | 20 ++++---- ui-components/typesoftoolbarbuttons.md | 4 +- 7 files changed, 68 insertions(+), 45 deletions(-) rename _includes/live-demos/{autocompleter => autocompleter-autocompleteitem}/index.html (100%) create mode 100644 _includes/live-demos/autocompleter-autocompleteitem/index.js create mode 100644 _includes/live-demos/autocompleter-cardmenuitem/index.html rename _includes/live-demos/{autocompleter => autocompleter-cardmenuitem}/index.js (72%) diff --git a/_includes/components/choice-menu-items.md b/_includes/components/choice-menu-items.md index 33448f242..61a1db20e 100644 --- a/_includes/components/choice-menu-items.md +++ b/_includes/components/choice-menu-items.md @@ -6,21 +6,12 @@ Choice menu items are a special type of menu item used for split toolbar button | Name | Value | Requirement | Description | | ---- | ----- | ----------- | ----------- | +| value | any | required | A value that is passed to `onItemAction` when the choice menu item is clicked. | | text | string | optional | Text to display. | | icon | string | optional | {{site.predefinedIconsOnly}} | -| value | string | required | A value that is passed to `onItemAction` when the choice menu item is clicked. | | disabled | boolean | optional | default: false - Represents the menu item's state. When true, the menu item is unclickable. Toggled by the menu item's API. | | shortcut | string | optional | Text to display in the shortcut label. To register a shortcut, see: [Add custom shortcuts to TinyMCE]({{site.baseurl}}/advanced/keyboard-shortcuts/#addcustomshortcutstotinymce). | > **Note**: The `icon` option for choice menu items was added in {{site.productname}} 5.3. -#### API - -| Name | Value | Description | -| ---- | ----- | ----------- | -| isActive | () => boolean | Checks if the menu item is active. | -| setActive | (state: boolean) => void | Sets the menu item's active state. | -| isDisabled | () => boolean | Checks if the menu item is disabled. | -| setDisabled | (state: boolean) => void | Sets the menu item's disabled state. | - For an example of how choice menu items are used in split toolbar buttons, see: [Split button example and explanation]({{site.baseurl}}/ui-components/typesoftoolbarbuttons/#splitbuttonexampleandexplanation). \ No newline at end of file diff --git a/_includes/live-demos/autocompleter/index.html b/_includes/live-demos/autocompleter-autocompleteitem/index.html similarity index 100% rename from _includes/live-demos/autocompleter/index.html rename to _includes/live-demos/autocompleter-autocompleteitem/index.html diff --git a/_includes/live-demos/autocompleter-autocompleteitem/index.js b/_includes/live-demos/autocompleter-autocompleteitem/index.js new file mode 100644 index 000000000..d41033d66 --- /dev/null +++ b/_includes/live-demos/autocompleter-autocompleteitem/index.js @@ -0,0 +1,48 @@ +var specialChars = [ + { text: 'exclamation mark', value: '!' }, + { text: 'at', value: '@' }, + { text: 'hash', value: '#' }, + { text: 'dollars', value: '$' }, + { text: 'percent sign', value: '%' }, + { text: 'caret', value: '^' }, + { text: 'ampersand', value: '&' }, + { text: 'asterisk', value: '*' } +]; +tinymce.init({ + selector: 'textarea#autocompleter', + height: 250, + setup: function (editor) { + var onAction = function (autocompleteApi, rng, value) { + editor.selection.setRng(rng); + editor.insertContent(value); + autocompleteApi.hide(); + }; + + var getMatchedChars = function (pattern) { + return specialChars.filter(function (char) { + return char.text.indexOf(pattern) !== -1; + }); + }; + + /* An autocompleter that allows you to insert special characters */ + editor.ui.registry.addAutocompleter('specialchars', { + ch: ':', + minChars: 1, + columns: 'auto', + onAction: onAction, + fetch: function (pattern) { + return new tinymce.util.Promise(function (resolve) { + var results = getMatchedChars(pattern).map(function (char) { + return { + type: 'autocompleteitem', + value: char.value, + text: char.text, + icon: char.value + } + }); + resolve(results); + }); + } + }); + } +}); diff --git a/_includes/live-demos/autocompleter-cardmenuitem/index.html b/_includes/live-demos/autocompleter-cardmenuitem/index.html new file mode 100644 index 000000000..abb9c8c67 --- /dev/null +++ b/_includes/live-demos/autocompleter-cardmenuitem/index.html @@ -0,0 +1,4 @@ + diff --git a/_includes/live-demos/autocompleter/index.js b/_includes/live-demos/autocompleter-cardmenuitem/index.js similarity index 72% rename from _includes/live-demos/autocompleter/index.js rename to _includes/live-demos/autocompleter-cardmenuitem/index.js index afc7bf962..fd5be48c2 100644 --- a/_includes/live-demos/autocompleter/index.js +++ b/_includes/live-demos/autocompleter-cardmenuitem/index.js @@ -9,7 +9,7 @@ var specialChars = [ { text: 'asterisk', value: '*' } ]; tinymce.init({ - selector: 'textarea#autocompleter', + selector: 'textarea#autocompleter-cardmenuitem', height: 250, setup: function (editor) { var onAction = function (autocompleteApi, rng, value) { @@ -24,27 +24,6 @@ tinymce.init({ }); }; - /* An autocompleter that allows you to insert special characters */ - editor.ui.registry.addAutocompleter('specialchars', { - ch: ':', - minChars: 1, - columns: 'auto', - onAction: onAction, - fetch: function (pattern) { - return new tinymce.util.Promise(function (resolve) { - var results = getMatchedChars(pattern).map(function (char) { - return { - type: 'autocompleteitem', - value: char.value, - text: char.text, - icon: char.value - } - }); - resolve(results); - }); - } - }); - /** * An autocompleter that allows you to insert special characters. * Items are built using the CardMenuItem. @@ -85,6 +64,5 @@ tinymce.init({ }); } }); - }, - content_style: {{site.liveDemoIframeCSSStyles}} + } }); diff --git a/ui-components/autocompleter.md b/ui-components/autocompleter.md index 0787243b1..30ae1afa4 100644 --- a/ui-components/autocompleter.md +++ b/ui-components/autocompleter.md @@ -8,7 +8,7 @@ keywords: autocomplete ## Overview -An `autocompleter` enables users to quickly find and select from a pre-populated list of values as they type, leveraging searching and filtering. It provides suggestions to insert while the user is typing into the content. For example, with the [charmap]({{site.baseurl}}/plugins/opensource/charmap/) plugin enabled, typing **:amp** should show the ampersand item in the menu. To activate the `autocompleter`, the user must precede the trigger character (colon in this case) with a separator character, such as a space or a newline. Pressing `esc` should close the autocomplete menu. +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. ## How to create custom autocompleters @@ -26,7 +26,7 @@ The two arguments this method take are: | Name | Value | Requirement | Description | | ---- | ----- | ----------- | ----------- | | ch | string (of one character) | Required | The character to trigger the autocompleter. | -| fetch | `(pattern: string, maxResults: number, fetchOptions: Record) => Promise` | Required | A function that is 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. | +| fetch | `(pattern: string, maxResults: number, fetchOptions: Record) => Promise` | Required | A function that is 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. | | onAction | `(api, rng: Range, value: string) => void` | Required | A function invoked when a fetched item is selected. | | columns | number or 'auto' | Optional | default: auto - The number of columns to show. If set to `1` column, then icons and text are displayed, otherwise only icons are displayed. | | matches | `(rng: Range, text: string, pattern: string) => boolean` | Optional | default: `isStartOfWord` - A predicate function that takes a range, the current text node content and the matched text content and returns a boolean indicating if the autocompleter should trigger. | @@ -74,9 +74,9 @@ The `CardMenuItem` allows customization of layout and content. This is done by c | Name | Value | Requirement | Description | | ---- | ----- | ----------- | ----------- | +| items | array | required | An array of [CardItems](#carditems) | | value | string | optional | Value of the item. This will be passed to the `onAction` callback when selected. | | label | string | optional | Label of the item. Will be used for [accessibility purposes](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA). | -| items | array | required | An array of [CardItems](#carditems) | ```js { @@ -102,10 +102,10 @@ A `CardContainer` is a layout component used to apply a layout to an array of ca | Name | Value | Requirement | Description | | ---- | ----- | ----------- | ----------- | +| items | array | required | An array of [CardItems](#carditem) | | direction | `'vertical'` or `'horizontal'` | optional | default: `horizontal` - directionality of subitems | | align | `'left'` or `'right'` | optional | default: `left` - horizontal alignment of subitems | | valign | `'top'`, `'middle'` or `'bottom'` | optional | default: `middle` - vertical alignment of subitems | -| items | array | required | An array of [CardItems](#carditem) | ```js { @@ -125,7 +125,7 @@ A `CardContainer` is a layout component used to apply a layout to an array of ca | ---- | ----- | ----------- | ----------- | | text | string | required | Text to display | | name | string | optional | Identifier used to reference specific CardText items. The autocompleter will use this for the text-highlight functionality. | -| classes | array | required | Array of classes to apply. Note: restrict usage to styles that won't affect the layout, such as `font-style`. | +| classes | array | optional | Array of classes to apply. Note: restrict usage to styles that won't affect the layout, such as `font-style`. | ```js { @@ -144,7 +144,7 @@ A `CardContainer` is a layout component used to apply a layout to an array of ca | ---- | ----- | ----------- | ----------- | | src | string | required | Image source to use | | alt | string | required | Image alt text | -| classes | array | required | Array of classes to apply. Note: restrict usage to styles that won't affect the layout, such as `border-radius`. | +| classes | array | optional | Array of classes to apply. Note: restrict usage to styles that won't affect the layout, such as `border-radius`. | ```js { @@ -162,8 +162,10 @@ A `CardContainer` is a layout component used to apply a layout to an array of ca | hide | `() => void` | Hides the autocompleter menu. | | reload | `(fetchOptions: Record) => void` | Hides the autocompleter menu and fetches new menu items. The `fetchOptions` will be passed to the autocompleter `fetch` callback. | -## Interactive example +## Interactive examples + +The following examples show how to create a special characters autocompleter. The first example uses the standard autocompleter item and will show when user types the colon (`:`) character and at least one additional character. The second uses [CardMenuItems](#cardmenuitem) and will show when a user types a hyphen (`-`) character and at least one additional character. -The following shows two examples of how to create a charmap autocompleter. The first autocompleter is constructed using the standard autocompleter item and will show whenever a `:` character is typed plus at least one additional character. The second autocompleter is constructed using [CardMenuItems](#cardmenuitem) and will show whenever a `-` character is typed plus at least one additional character. +{% include live-demo.html id="autocompleter-autocompleteitem" height="300" tab="js" %} -{% include live-demo.html id="autocompleter" height="300" tab="js" %} +{% include live-demo.html id="autocompleter-cardmenuitem" height="300" tab="js" %} diff --git a/ui-components/typesoftoolbarbuttons.md b/ui-components/typesoftoolbarbuttons.md index 6db0ba7f3..850d8223a 100644 --- a/ui-components/typesoftoolbarbuttons.md +++ b/ui-components/typesoftoolbarbuttons.md @@ -103,10 +103,10 @@ For example: The table plugin's `table` toolbar button opens a menu similar to t | Name | Value | Requirement | Description | |------| ------| ------------| ----------- | +| fetch | (success: (menu) => void) => void | required | Function that takes a callback which must be passed the list of options for the button's dropdown. | | text | string | optional | Text to display if no icon is found. | | icon | string | optional | {{site.predefinedIconsOnly}} | | tooltip | string | optional | Text for button tooltip. | -| fetch | (success: (menu) => void) => void | required | Function that takes a callback which must be passed the list of options for the button's dropdown. | | onSetup | (api) => (api) => void | optional | default: () => () => {} - Function that's invoked when the button is rendered. | > **Note**: See [below](#onsetupexplanation) for details on how to configure `onSetup`. @@ -143,7 +143,7 @@ A split button contains a basic button and a menu button, wrapped up into one to | onAction | (api) => void | Primary button | required | Function invoked when the basic button section is clicked. | | select | (value: string) => boolean | Choice menu items | optional | default: false - Function run on each option when the menu is opened to determine if it should be highlighted as active. | | columns | number or `'auto'` | Drop-down menu | optional | default: 1 - Number of columns for the list of options. When set to more than 1 column, only the icon for each item will be shown. | -| fetch | (success: (menu) => void) => void | Drop-down menu | required | A callback function that should be passed a list of choice menu items for the dropdown menu. | +| fetch | (success: (menu) => void) => void | Drop-down menu | required | A callback function that should be passed a list of [choice menu items](#choicemenuitems) for the dropdown menu. | | onItemAction | (api, value) => void | Choice menu items | required | Function invoked when a dropdown list option is clicked. The `value` is passed from the selected choice menu item. | | onSetup | (api) => (api) => void | All | optional | default: () => () => {} - Function invoked when the button is rendered. |