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

DOC-466: fix split button docs and shortcut docs (#1573)

pull/1589/head
Tyler Kelly 5 years ago
committed by GitHub
parent
b2c7136299
commit
36ab20e098
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 115 additions and 30 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. 2
      _config.yml
  2. 11
      _includes/codepens/custom-shortcut/index.html
  3. 11
      _includes/codepens/custom-shortcut/index.js
  4. 4
      _includes/codepens/custom-toolbar-split-button/index.js
  5. 28
      _includes/components/choice-menu-items.md
  6. 11
      _includes/misc/shortcut-os-mappings.md
  7. 13
      advanced/keyboard-shortcuts.md
  8. 4
      ui-components/contextform.md
  9. 4
      ui-components/dialog.md
  10. 4
      ui-components/dialogcomponents.md
  11. 15
      ui-components/menuitems.md
  12. 36
      ui-components/typesoftoolbarbuttons.md
  13. 2
      ui-components/urldialog.md

2
_config.yml
View File

@ -58,6 +58,8 @@ thirdPartyInteg: "> **Important**: This Integration is maintained by a third-par
moxieMNotOnCloud: "> **Note**: The MoxieManager plugin is _not_ provided on the Tiny Cloud, and is provided as a self-hosted solution only."
predefinedIconsOnly: "Name of the icon to be displayed. Must correspond to an icon: in the [icon pack](https://www.tiny.cloud/docs/advanced/editor-icon-identifiers/), in a [custom icon pack](https://www.tiny.cloud/docs/advanced/creating-an-icon-pack/), or added using the [`addIcon` API](https://www.tiny.cloud/docs/api/tinymce.editor.ui/tinymce.editor.ui.registry/#addicon)."
exclude:
- Dockerfile
- Gemfile

11
_includes/codepens/custom-shortcut/index.html
View File

@ -0,0 +1,11 @@
<textarea id="custom-shortcut">
<p>To add a yellow highlight to this text:</p>
<ul>
<li>Select some text
<ul>
<li>On PC, press: Ctrl+Alt+Y</li>
<li>On MacOS, press: Command+Option+Y</li>
</ul>
</li>
</ul>
</textarea>

11
_includes/codepens/custom-shortcut/index.js
View File

@ -0,0 +1,11 @@
tinymce.init({
selector: "textarea#custom-shortcut",
content_css: '//www.tiny.cloud/css/codepen.min.css',
height: 300,
setup: function (editor) {
editor.addShortcut(
'meta+alt+y', 'Add yellow highlight to selected text.', function () {
editor.execCommand('hilitecolor', false , '#FFFF00');
});
}
});

4
_includes/codepens/custom-toolbar-split-button/index.js
View File

@ -6,6 +6,8 @@ tinymce.init({
setup: function (editor) {
editor.ui.registry.addSplitButton('myButton', {
text: 'My Button',
icon: 'info',
tooltip: 'This is an example split-button',
onAction: function () {
editor.insertContent('<p>You clicked the main button</p>');
},
@ -16,11 +18,13 @@ tinymce.init({
var items = [
{
type: 'choiceitem',
icon: 'notice',
text: 'Menu item 1',
value: '&nbsp;<em>You clicked menu item 1!</em>'
},
{
type: 'choiceitem',
icon: 'warning',
text: 'Menu item 2',
value: '&nbsp;<em>You clicked menu item 2!</em>'
}

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

@ -0,0 +1,28 @@
#### Choice menu items
Choice menu items are a special type of menu item used for split toolbar button menu items. For information on split buttons, see: [Split toolbar buttons]({{site.baseurl}}/ui-components/typesoftoolbarbuttons/#splitbutton).
##### Config options
| Name | Value | Requirement | Description |
| ---- | ----- | ----------- | ----------- |
| 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 | Sets a keyboard shortcut for activating the menu item, such as: `shortcut: 'Ctrl+Alt+Delete'`. For information on available shortcut modifiers, see: [Shortcut modifier key mappings](#shortcutmodifierkeymappings). |
> **Note**: The `icon` option for choice menu items was added in {{site.productname}} 5.3.
####{% include misc/shortcut-os-mappings.md %}
##### 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).

11
_includes/misc/shortcut-os-mappings.md
View File

@ -0,0 +1,11 @@
## Shortcut modifier key mappings
When creating shortcuts for {{site.productname}}, the following modifiers can be used. Some modifiers map to different keys, depending on the user's operating system.
| Modifier | PC | MacOS |
|----------|-----------|----------------|
| `Meta` | Ctrl | Command |
| `Shift` | Shift | Shift |
| `Ctrl` | Ctrl | Control |
| `Alt` | Alt | Option |
| `Access` | Shift+Alt | Control+Option |

13
advanced/keyboard-shortcuts.md
View File

@ -63,4 +63,15 @@ This is a list of available keyboard shortcuts within the editor user interface.
## Add custom shortcuts to TinyMCE
Refer to the [addShortcut]({{site.baseurl}}/api/tinymce/tinymce.editor/#addshortcut) and [tinymce.Shortcuts]({{site.baseurl}}/api/tinymce/tinymce.shortcuts/) sections to add custom keyboard shortcuts to {{site.productname}}.
> **Important**: Adding a custom shortcut with a keyboard combination that conflicts with an existing {{site.productname}} or browser shortcut will override the existing shortcut.
To add a custom keyboard shortcut to {{site.productname}}, use either:
* [The `tinymce.Editor.addShortcut` API]({{site.baseurl}}/api/tinymce/tinymce.editor/#addshortcut).
* [The `tinymce.Shortcuts.add` API]({{site.baseurl}}/api/tinymce/tinymce.shortcuts/).
#{% include misc/shortcut-os-mappings.md %}
### Example: Custom keyboard shortcut
{% include codepen.html id="custom-shortcut" tab="js" %}

4
ui-components/contextform.md
View File

@ -67,7 +67,7 @@ The definition of a context form button is very similar to the definition of a n
| disabled | boolean; | Optional | default: false - Represents button state. Is toggled by the button's API |
| tooltip | string; | Optional | Text for button tooltip. |
| text | string; | Optional | Text to display if no icon is found. |
| icon | string; | Optional | It displays the icon corresponding to the icon name that has been defined in the icon pack. |
| icon | string; | Optional | {{site.predefinedIconsOnly}} |
| onSetup | (togglebuttonApi) => (togglebuttonApi) => void; | Optional | default: () => () => {} - Function that's invoked when the button is rendered. |
Where the `buttonApi` is the same as a regular toolbar button and `FormApi` has (getValue: () => string, hide: () => void)
@ -86,7 +86,7 @@ The context form toggle button is very similar to the a normal toolbar toggle bu
| disabled | boolean; | Optional | default: false - Represents button state. Is toggled by the button's API |
| tooltip | string; | Optional | Text for button tooltip. |
| text | string; | Optional | Text to display if no icon is found. |
| icon | string; | Optional | It displays the icon corresponding to the icon name that has been defined in the icon pack. |
| icon | string; | Optional | {{site.predefinedIconsOnly}} |
| onSetup | (togglebuttonApi) => (togglebuttonApi) => void; | Optional | default: () => () => {} - Function that's invoked when the button is rendered. |
Where the `toggleButtonApi` is the same as a regular toolbar toggle button.

4
ui-components/dialog.md
View File

@ -147,7 +147,7 @@ A **button** is a clickable component that can contain text or an icon. There ar
| type | `'submit'` or `'cancel'` or `'custom'` or `'menu'` | required | Must be `'submit'`, `'cancel'`, `'custom'` or `'menu'` based on the type of callback function that should be invoked when the button is clicked. |
| text | string | required | Text to display in the button if `icon` is not specified. Also used for the button's `title` attribute. |
| name | string | optional | An identifier for the button. If not specified, the button will be assigned a randomly generated `name`. |
| icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in the icon pack. **When configured, the button will display the icon instead of text.** |
| icon | string | optional | {{site.predefinedIconsOnly}} **When configured, the button will display the icon instead of text.** |
| primary | boolean | optional | default: `false` - Whether to style the button as a primary or secondary button. |
| disabled | boolean | optional | default: `false` - When `true`, the button will be disabled when the dialog loads. |
| align | `'end'` or `'start'` | optional | default: `'end'` - When set to `'end'` the button will display on the right-hand side of the dialog. When set to `'start'` the button will display on the left-hand side. |
@ -199,7 +199,7 @@ The following options can be specified for a dialog menu button:
| items | array | required | An array of [dialog menu items](#dialogmenuitems). |
| name | string | optional | An identifier for the button. If not specified, the button will be assigned a randomly generated `name`. |
| text | string | optional | Text to display if no icon is found. |
| icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in the icon pack. |
| icon | string | optional | {{site.predefinedIconsOnly}} |
| tooltip | string | optional | Text for button tooltip. |
###### Dialog menu items

4
ui-components/dialogcomponents.md
View File

@ -174,7 +174,7 @@ Clicking the icon in the alert banner will fire the `onAction` function in the d
| type | `'alertbanner'` | required | The component type. Must be `'alertbanner'`. |
| text | string | required | HTML text to display in the alertbanner. |
| level | `'info'`, `'warn'`, `'error'` or `'success'` | required | The alertbanner's level, which determines its styling. |
| icon | string | required | Name of the icon to be displayed. Must correspond to an icon in the icon pack. |
| icon | string | required | {{site.predefinedIconsOnly}} |
| url | string | optional | A URL that is passed to `onAction` when the icon button is clicked. |
```js
@ -200,7 +200,7 @@ A **button** is a clickable component that can contain text or an icon. There ar
| type | `'button'` | required | The component type. Must be `'button'`. |
| text | string | required | Text to display in the button **if icon is not specified**. Also used for the button's `title` attribute. |
| name | string | optional | A identifier for the button. If not specified, the button will be assigned a randomly generated name. |
| icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in the icon pack. **When configured, the button will display the icon instead of text.** |
| icon | string | optional | {{site.predefinedIconsOnly}} **When configured, the button will display the icon instead of text.** |
| primary | boolean | optional | default: `false` - Whether to style the button as a primary or secondary button. |
| borderless | boolean | optional | default: `false` - Whether to style the button without a border and background color. |

15
ui-components/menuitems.md
View File

@ -66,11 +66,14 @@ A basic menu item triggers its `onAction` function when clicked.
| Name | Value | Requirement | Description |
| ---- | ----- | ----------- | ----------- |
| text | string | optional | Text to display if no icon is found. |
| icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in the [icon pack]({{site.baseurl}}/advanced/editor-icon-identifiers/). |
| icon | string | optional | {{site.predefinedIconsOnly}} |
| value | string | optional | A value to associate with the menu item. |
| 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. |
| onSetup | (api) => (api) => void | optional | default: () => () => {} - Function invoked when the menu item is rendered, each time its menu is opened. |
| onAction | (api) => void | required | Function invoked when the menu item is clicked. |
| shortcut | string | optional | Sets a keyboard shortcut for activating the menu item, such as: `shortcut: 'Ctrl+Alt+Delete'`. For information on available shortcut modifiers, see: [Shortcut modifier key mappings](#shortcutmodifierkeymappings). |
###{% include misc/shortcut-os-mappings.md %}
#### API
@ -108,10 +111,14 @@ A nested menu item is a menu item with a submenu. Registering a submenu this way
| Name | Value | Requirement | Description |
| ---- | ----- | ----------- | ----------- |
| text | string | optional | Text to display if no icon is found. |
| icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in the [icon pack]({{site.baseurl}}/advanced/editor-icon-identifiers/). |
| icon | string | optional | {{site.predefinedIconsOnly}} |
| value | string | optional | A value to associate with the menu item. |
| onSetup | (api) => (api) => void | optional | default: () => () => {} - Function invoked when the menu item is rendered, each time its menu is opened. |
| getSubmenuItems | () => string or MenuItem[] | required | Function invoked when the menu item is clicked to open its submenu. Must return either a space separated string of registered menu names or an array of basic, toggle or nested menu items specifications. |
| shortcut | string | optional | Sets a keyboard shortcut for activating the menu item, such as: `shortcut: 'Ctrl+Alt+Delete'`. For information on available shortcut modifiers, see: [Shortcut modifier key mappings](#shortcutmodifierkeymappings2). |
<a class="anchor" id="shortcutmodifierkeymappings2"></a>
###{% include misc/shortcut-os-mappings.md %}
#### API
@ -157,7 +164,7 @@ A toggle menu item triggers its `onAction` when clicked. It also has a concept o
| Name | Value | Requirement | Description |
| ---- | ----- | ----------- | ----------- |
| text | string | optional | Text to display. |
| icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in the [icon pack]({{site.baseurl}}/advanced/editor-icon-identifiers/). |
| icon | string | optional | {{site.predefinedIconsOnly}} |
| value | string | optional | A value to associate with the menu item. |
| active | boolean | optional | Initial state value for the toggle menu item |
| 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. |
@ -205,4 +212,4 @@ tinymce.init({
}
});
```
```

36
ui-components/typesoftoolbarbuttons.md
View File

@ -23,7 +23,7 @@ A basic button triggers its `onAction` function when clicked.
| Name | Value | Requirement | Description |
| ---- | ----- | ----------- | ----------- |
| text | string | optional | Text to display if no icon is found. |
| icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in [icon pack]({{site.baseurl}}/advanced/editor-icon-identifiers/). |
| icon | string | optional | {{site.predefinedIconsOnly}} |
| tooltip | string | optional | Text for button tooltip. |
| disabled | boolean | optional | default: false - Represents the button's state. When true, button is unclickable. Toggled by the button's API. |
| onSetup | (api) => (api) => void | optional | default: () => () => {} - Function invoked when the button is rendered. |
@ -61,7 +61,7 @@ A toggle button triggers an action when clicked but also has a concept of state.
| Name | Value | Requirement | Description |
|------| ------| ------------| ----------- |
| text | string | optional | Text to display if no icon is found. |
| icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in the [icon pack]({{site.baseurl}}/advanced/editor-icon-identifiers/). |
| icon | string | optional | {{site.predefinedIconsOnly}} |
| tooltip | string | optional | Text for button tooltip. |
| disabled | boolean | optional | default: false - Represents the button's state. When true, button is unclickable. Toggled by the button's API. |
| active | boolean | optional | default: false - Represents the button's state. When true, button is highlighted. Toggled by the button's API. |
@ -81,7 +81,7 @@ A toggle button triggers an action when clicked but also has a concept of state.
#### Toggle button example and explanation
{% include codepen.html id="custom-toolbar-toggle-button" %}
{% include codepen.html id="custom-toolbar-toggle-button" tab="js" %}
The example above adds two custom **strikethrough** buttons with the same `onAction` configuration. The configuration uses `editor.execCommand(command, ui, args)` to execute `mceToggleFormat`. This editor method toggles the specified format on and off, but only works for [formats]({{site.baseurl}}/configure/content-formatting/#formats) that are already registered with the editor. In this example, `strikethrough` is the registered format.
@ -97,20 +97,18 @@ The callback given to `editor.formatter.formatChanged` is a function that takes
A split button contains a basic button and a menu button, wrapped up into one toolbar item. Clicking the menu button section opens a dropdown list. The basic button section and the menu items can be configured to trigger different actions when clicked.
> Example: Font select dropdown.
#### Config options
| Name | Value | Requirement | Description |
|------| ------| ------------| ----------- |
| text | string | optional | Text displayed if no icon is found. |
| icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in the [icon pack]({{site.baseurl}}/advanced/editor-icon-identifiers/). |
| select | (value: string) => boolean | optional | default: false - Function run on each option to determine if it should be highlighted as active. |
| columns | string | optional | default: 1 - Number of columns for the list of options. |
| fetch | (success: (menu) => void) => void | required | Function that takes a callback which must be passed the list of options for the button's dropdown. |
| onAction | (api) => void | required | Function invoked when the basic button section is clicked. |
| onItemAction | (api, value) => void | required | Function invoked when a dropdown list option is clicked. |
| onSetup | (api) => (api) => void | optional | default: () => () => {} - Function invoked when the button is rendered. |
| Name | Value | Target component | Requirement | Description |
|--------------|-----------------------------------|-------------------|-------------|------------------------------------------------------------------------------------------------------------------------------------|
| text | string | Primary button | optional | Text displayed if no icon is found. |
| icon | string | Primary button | optional | {{site.predefinedIconsOnly}} |
| 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 | string | 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. |
| 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. |
> Note: See [below](#onsetupexplanation) for details on how to configure `onSetup`.
@ -135,6 +133,8 @@ A split button is similar to a basic button in that they both require an `onActi
The `fetch` function is called whenever the split button's drop-down menu is opened. It is a function that takes a callback and passes it an array of menu items to be rendered in the button's drop-down menu. This allows for asynchronous fetching of the menu items.
#{% include components/choice-menu-items.md %}
### Menu button
A toolbar menu button is a toolbar button that opens a menu when clicked. This menu can also contain submenus. This is useful for grouping together actions that would otherwise be several buttons on the toolbar. It can also be used to reduce visual clutter and save UI space, as menubar menu items and some toolbar buttons could be moved into a toolbar menu button. Potentially, all menubar menu items could be moved into toolbar menu buttons, allowing for the editor to be used without a menubar at all.
@ -146,7 +146,7 @@ A toolbar menu button is a toolbar button that opens a menu when clicked. This m
| Name | Value | Requirement | Description |
|------| ------| ------------| ----------- |
| text | string | optional | Text to display if no icon is found. |
| icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in the [icon pack]({{site.baseurl}}/advanced/editor-icon-identifiers/). |
| 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. |
@ -185,7 +185,7 @@ A group toolbar button is a toolbar button that contains a collection of other t
| Name | Value | Requirement | Description |
|------| ------| ------------| ----------- |
| text | string | optional | Text to display if no icon is found. |
| icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in the [icon pack]({{site.baseurl}}/advanced/editor-icon-identifiers/). |
| icon | string | optional | {{site.predefinedIconsOnly}} |
| tooltip | string | optional | Text for button tooltip. |
| items | string or LabelledToolbar[] | required | A string of space separated toolbar button names, or an array of [labelled toolbar buttons]({{site.baseurl}}/configure/editor-appearance/#addingtoolbargrouplabels). |
| onSetup | (api) => (api) => void | optional | default: () => () => {} - Function that's invoked when the button is rendered. |
@ -209,4 +209,4 @@ The example above configures a custom **alignment** group toolbar button. When c
### `onSetup` explanation
{% include release-notes/onSetup.md %}
{% include release-notes/onSetup.md %}

2
ui-components/urldialog.md
View File

@ -59,7 +59,7 @@ A **button** is a clickable component that can contain text or an icon. There ar
| type | `'cancel'` or `'custom'` | required | Must be `'cancel'` or `'custom'` based on the type of callback function that should be invoked when the button is clicked. |
| text | string | required | Text to display in the button if `icon` is not specified. Also used for the button's `title` attribute. |
| name | string | optional | An identifier for the button. If not specified, the button will be assigned a randomly generated `name`. |
| icon | string | optional | Name of the icon to be displayed. Must correspond to an icon in the icon pack. **When configured, the button will display the icon instead of text.** |
| icon | string | optional | {{site.predefinedIconsOnly}} **When configured, the button will display the icon instead of text.** |
| primary | boolean | optional | default: `false` - Whether to style the button as a primary or secondary button. |
| disabled | boolean | optional | default: `false` - When `true`, the button will be disabled when the dialog loads. |
| align | `'end'` or `'start'` | optional | default: `'end'` - When set to `'end'` the button will display on the right-hand side of the dialog. When set to `'start'` the button will display on the left-hand side. |

Write Preview
Loading…
Cancel
Save