|
1 | 1 | --- |
2 | | -description: Information on how to work with TinyMCE plugins in the rich text editor. |
| 2 | +description: Information on how to work with Tiptap plugins in the rich text editor. |
3 | 3 | --- |
4 | 4 |
|
5 | 5 | # Plugins |
6 | 6 |
|
7 | | -The Rich Text Editor (RTE) in Umbraco is based on the open source editor [TinyMCE](https://www.tiny.cloud/). TinyMCE is a highly customizable editor, and it is possible to extend the functionality of the editor by adding plugins. |
| 7 | +Are plugins available with Tiptap? |
8 | 8 |
|
9 | | -TinyMCE comes with a lot of plugins out of the box, but it is also possible to create your own plugins. This article will show you how to add a custom plugin to the rich text editor. |
10 | | - |
11 | | -### Open-Source Plugins |
12 | | - |
13 | | -TinyMCE has a lot of open-source plugins available. You can find a list of these plugins on the [TinyMCE website](https://www.tiny.cloud/docs/tinymce/6/plugins/#open-source-plugins). |
14 | | - |
15 | | -### Premium Plugins |
16 | | - |
17 | | -TinyMCE also has a number of [premium plugins](https://www.tiny.cloud/docs/tinymce/6/plugins/#premium-plugins) available. These plugins are only available for [paid TinyMCE subscriptions](https://www.tiny.cloud/pricing/). They can be added to the rich text editor by [adding a bit of configuration](#adding-a-premium-plugin). |
18 | | - |
19 | | -## Adding a Plugin |
20 | | - |
21 | | -To enable plugins in the rich text editor, you need to add an extension type called `tinyMcePlugin` in a manifest file. The manifest file is a JSON file that describes the plugin and how it should be loaded. You can add a plugin such as the open source [Word Count Plugin](https://www.tiny.cloud/docs/tinymce/6/wordcount/) to the rich text editor. You can also define your own custom plugin to extend the functionality of the editor. This way you can add custom buttons, dialogs, or other features to the editor. |
22 | | - |
23 | | -{% hint style="info" %} |
24 | | -The manifest file should be placed in a folder in `App_Plugins/{YourPackageName}`, with the name `umbraco-package.json`. Learn how to use the [package manifests](../../../../../extending/property-editors/package-manifest.md). |
25 | | -{% endhint %} |
26 | | - |
27 | | -{% code title="App_Plugins/YourPackageName/umbraco-package.json" lineNumbers="true" %} |
28 | | - |
29 | | -```json |
30 | | -{ |
31 | | - "name": "My TinyMCE Plugin", |
32 | | - "version": "1.0.0", |
33 | | - "extensions": [ |
34 | | - { |
35 | | - "type": "tinyMcePlugin", |
36 | | - "alias": "mytinymceplugin", |
37 | | - "name": "My TinyMCE Plugin", |
38 | | - "meta": { |
39 | | - "config": { |
40 | | - "plugins": ["wordcount"], |
41 | | - "statusbar": true |
42 | | - } |
43 | | - } |
44 | | - } |
45 | | - ] |
46 | | -} |
47 | | -``` |
48 | | - |
49 | | -{% endcode %} |
50 | | - |
51 | | -The example above shows how to add the open-source [Word Count Plugin](https://www.tiny.cloud/docs/tinymce/6/wordcount/) to the rich text editor. The plugin is added to the `Plugins` array in the configuration. The plugin itself will be shown in the statusbar of the rich text editor, so the `statusbar` option is also added to the `config` object. |
52 | | - |
53 | | -## Creating a Custom Plugin |
54 | | - |
55 | | -If you want to create your own plugin, you should in general follow the [TinyMCE documentation](https://www.tiny.cloud/docs/tinymce/latest/creating-a-plugin/). However, there are a few things you need to be aware of to load the plugin in Umbraco. See the example below. |
56 | | - |
57 | | -### Examples |
58 | | - |
59 | | -Load a custom plugin that gives you the ability to interact with the global `tinymce` editor object. |
60 | | - |
61 | | -Here we are loading a custom plugin called `myrteplugin` and adding a button to the editor called `myrtebutton`. When the button is clicked, it will insert the text `Hello World!` into the editor. |
62 | | - |
63 | | -<figure><img src="images/my-rte-button-editor.jpg" alt="Rich text editor showing a custom button"><figcaption><p>The text "Hello World!" shows up after clicking the button</p></figcaption></figure> |
64 | | - |
65 | | -1.**Add a manifest file** |
66 | | - |
67 | | -First we create an `umbraco-package.json` file which will contain the manifest for the plugin. This adds a button to the toolbar in the rich text editor, which editors can enable on the Data Type. We are also letting the rich text editor know it should load the plugin from the `plugin.js` file. |
68 | | - |
69 | | -{% code title="App_Plugins/MyRtePlugin/umbraco-package.json" lineNumbers="true" %} |
70 | | - |
71 | | -```json |
72 | | -{ |
73 | | - "name": "My TinyMCE Plugin", |
74 | | - "version": "1.0.0", |
75 | | - "extensions": [ |
76 | | - { |
77 | | - "type": "tinyMcePlugin", |
78 | | - "alias": "myrteplugin", |
79 | | - "name": "My TinyMCE Plugin", |
80 | | - "js": "/App_Plugins/MyRtePlugin/plugin.js", |
81 | | - "meta": { |
82 | | - "toolbar": [ |
83 | | - { |
84 | | - "alias": "myrtebutton", |
85 | | - "label": "My RTE Button", |
86 | | - "icon": "code-sample" |
87 | | - } |
88 | | - ] |
89 | | - } |
90 | | - } |
91 | | - ] |
92 | | -} |
93 | | -``` |
94 | | - |
95 | | -{% endcode %} |
96 | | - |
97 | | -2.**Add the plugin.js file** |
98 | | - |
99 | | -The `plugin.js` file should contain the JavaScript code for the plugin. The file is loaded as a JavaScript module and must export a default class that extends the `UmbTinyMcePluginBase` class. |
100 | | - |
101 | | -{% hint style="info" %} |
102 | | -The `UmbTinyMcePluginBase` class is a class provided by Umbraco that you can use to create your own plugins. The class is a wrapper around the TinyMCE plugin API. We can use the `args` object on the constructor to access the TinyMCE editor instance and other useful properties. |
103 | | -{% endhint %} |
104 | | - |
105 | | -{% code title="App_Plugins/MyTinyMCEPlugin/plugin.js" lineNumbers="true" %} |
106 | | - |
107 | | -```js |
108 | | -import { UmbTinyMcePluginBase } from '@umbraco-cms/backoffice/tiny-mce'; |
109 | | - |
110 | | -export default class UmbTinyMceMediaPickerPlugin extends UmbTinyMcePluginBase { |
111 | | - /** |
112 | | - @param args {import('@umbraco-cms/backoffice/tiny-mce').TinyMcePluginArguments} |
113 | | - */ |
114 | | - constructor(args: TinyMcePluginArguments) { |
115 | | - super(args); |
116 | | - |
117 | | - // Add your plugin code here |
118 | | - args.editor.ui.registry.addButton('myrtebutton', { |
119 | | - text: 'My RTE Button', |
120 | | - icon: 'code-sample', |
121 | | - onAction: () => { |
122 | | - args.editor.insertContent('Hello World!'); |
123 | | - } |
124 | | - }); |
125 | | - } |
126 | | -} |
127 | | -``` |
128 | | - |
129 | | -{% endcode %} |
130 | | - |
131 | | -The button must be added to the toolbar in the rich text editor configuration. |
132 | | - |
133 | | -<figure><img src="images/my-rte-button.jpg" alt="Rich text editor configuration showing available options"><figcaption><p>Enable the button in the rich text editor configuration</p></figcaption></figure> |
134 | | - |
135 | | -You can go to any Document Type that uses the rich text editor and click the button to insert the text `Hello World!` after. |
136 | | - |
137 | | -You have full access to the `tinymce` editor object, so you can create any custom functionality you need. |
138 | | - |
139 | | -### Learn more |
140 | | - |
141 | | -* [TinyMCE documentation](https://www.tiny.cloud/docs/) |
142 | | -* [TinyMCE tutorial: Creating a plugin](https://www.tiny.cloud/docs/tinymce/latest/creating-a-plugin/) |
143 | | - |
144 | | -## Adding a premium plugin |
145 | | - |
146 | | -To add a premium plugin, you need to add the plugin name to the `plugins` array in the `config` object of a `tinyMcePlugin` extension. You also need to add a JavaScript module that can load up the cloud-hosted TinyMCE premium plugins bundle. |
147 | | - |
148 | | -{% hint style="info" %} |
149 | | -Premium plugins require a subscription at [TinyMCE Cloud](https://www.tiny.cloud/). You can go there and sign up for a free trial. You will get a Cloud API key that you can use to try out the premium plugins. |
150 | | -{% endhint %} |
151 | | - |
152 | | -1.**Declaring the plugin** |
153 | | - |
154 | | -Let us first add the [powerpaste](https://www.tiny.cloud/docs/tinymce/6/introduction-to-powerpaste/) plugin to the rich text editor. This plugin is a premium plugin that helps you paste content from Word documents and other sources. We will configure the plugin to allow local images and clean the HTML when pasting Word documents. |
155 | | - |
156 | | -{% code title="App_Plugins/MyRtePlugin/umbraco-package.json" lineNumbers="true" %} |
157 | | - |
158 | | -```json |
159 | | -{ |
160 | | - "name": "My TinyMCE Plugin", |
161 | | - "version": "1.0.0", |
162 | | - "extensions": [ |
163 | | - { |
164 | | - "type": "tinyMcePlugin", |
165 | | - "alias": "mytinymceplugin", |
166 | | - "name": "My TinyMCE Plugin", |
167 | | - "js": "/App_Plugins/MyRtePlugin/plugin.js", |
168 | | - "meta": { |
169 | | - "config": { |
170 | | - "plugins": ["powerpaste"], |
171 | | - "powerpaste_allow_local_images": "true", |
172 | | - "powerpaste_word_import": "clean" |
173 | | - } |
174 | | - } |
175 | | - } |
176 | | - ] |
177 | | -} |
178 | | -``` |
179 | | - |
180 | | -{% endcode %} |
181 | | - |
182 | | -2.**Creating the plugin.js file** |
183 | | - |
184 | | -The `plugin.js` file should contain the JavaScript code to load the cloud-hosted TinyMCE premium plugins bundle. You must replace `{Cloud API Key}` with your own Cloud API key. |
185 | | - |
186 | | -{% code title="App_Plugins/MyTinyMCEPlugin/plugin.js" lineNumbers="true" %} |
187 | | - |
188 | | -```js |
189 | | -import 'https://cdn.tiny.cloud/1/{Cloud API Key}/tinymce/6/plugins.min.js'; |
190 | | -``` |
191 | | - |
192 | | -{% endcode %} |
193 | | - |
194 | | -We have now enabled the `powerpaste` plugin. We have configured it to allow pasting in local images. It will prompt when pasting Word documents, but for HTML documents it will clean the HTML without prompting. |
195 | | - |
196 | | -{% hint style="info" %} |
197 | | -You can enable as many plugins as you want through the `plugins` array in the `config` object. You can even combine premium, open-source, and your own plugins as you see fit. |
198 | | -{% endhint %} |
199 | | - |
200 | | -See all the [available premium plugins](https://www.tiny.cloud/docs/tinymce/6/plugins/#premium-plugins) on the TinyMCE website. |
| 9 | +Will this be available from version 15? |
0 commit comments