Data
/
tinymce-docs
mirror of https://github.com/tinymce/tinymce-docs.git
2
0
Fork 0
Code Issues Releases Wiki Activity
Browse Source

TINY-6587: Review Autocompleter, Split Button, and Menu Button page (#2000)

pull/2008/head
Diogo Goncalves 4 years ago
committed by GitHub
parent
83acd423a8
commit
d2056003f9
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 68 additions and 45 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 11
      _includes/components/choice-menu-items.md
  2. 0
      _includes/live-demos/autocompleter-autocompleteitem/index.html
  3. 48
      _includes/live-demos/autocompleter-autocompleteitem/index.js
  4. 4
      _includes/live-demos/autocompleter-cardmenuitem/index.html
  5. 26
      _includes/live-demos/autocompleter-cardmenuitem/index.js
  6. 20
      ui-components/autocompleter.md
  7. 4
      ui-components/typesoftoolbarbuttons.md

11
_includes/components/choice-menu-items.md
View File

@ -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).

0
_includes/live-demos/autocompleter/index.html → _includes/live-demos/autocompleter-autocompleteitem/index.html
View File

48
_includes/live-demos/autocompleter-autocompleteitem/index.js
View File

@ -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);
});
}
});
}
});

4
_includes/live-demos/autocompleter-cardmenuitem/index.html
View File

@ -0,0 +1,4 @@
<textarea id="autocompleter-cardmenuitem">
<p>Type <b>-</b> below and then keep typing to reduce further matches. For example, typing <b>-amp</b> should show the ampersand item in the menu. Pressing esc should close the autocomplete menu.</p>
<p></p>
</textarea>

26
_includes/live-demos/autocompleter/index.js → _includes/live-demos/autocompleter-cardmenuitem/index.js
View File

@ -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}}
}
});

20
ui-components/autocompleter.md
View File

@ -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<string, any>) => Promise<AutocompleterContents[]>` | 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<string, any>) => Promise<AutocompleteItem[] | CardMenuItem[]>` | 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<string, any>) => 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" %}

4
ui-components/typesoftoolbarbuttons.md
View File

@ -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. |

Write Preview
Loading…
Cancel
Save