Skip to content

creating-a-plugin.adoc

Latest commit

 

History

History
122 lines (87 loc) · 5.94 KB

creating-a-plugin.adoc

File metadata and controls

122 lines (87 loc) · 5.94 KB

Create a plugin for {productname}

{productname} is designed to be easily extended by custom plugins; with APIs for registering custom plugins, and creating and localizing custom UI.

Requirements

To be recognized as a plugin by {productname}, the code for a custom plugin must have a JavaScript file with a single entry point that registers the plugin with {productname} using the PluginManager API. Any other code or resources can be in separate files and can be loaded in any standard manner. {productname} also has various APIs for loading scripts and stylesheets.

{productname} does not require any special file structure or tooling apart from these requirements, so custom plugins can be developed using most frameworks and tools.

Registering a custom plugin with {productname}

Register a custom plugin with {productname} using the PluginManager. PluginManager.add() takes a string for the plugin identifier and a function that contains the code for initializing the plugin.

The plugin identifier passed to PluginManager.add() is used by {productname} as an identifier string. It should:

  • Be an alphanumeric string,

  • Not contain any spaces or other whitespaces,

  • Be a unique identifier that does not match the IDs of plugins provided with {productname} or any other {productname} plugin in use.

If multiple plugins have the same identifier, one will override the others.

Optionally, the function passed to PluginManager.add() can return an object that contains data that {productname} or other plugins can use. {companyname} recommends including a getMetadata callback that returns an object containing data that can be used to populate the list of plugins in the Help plugin dialog. The metadata object should contain the following values:

  • name: A string that contains the plugin’s name, usually in a human-readable format.

  • url: A string that contains a URL, usually used to link to help documentation.

Example: plugin registration boilerplate

tinymce.PluginManager.add('pluginId', (editor, url) => {
  // add plugin code here

  return {
    getMetadata: () => ({
      name: 'Custom plugin',
      url: 'https://example.com/docs/customplugin'
    })
  }
});

Using custom plugins with {productname}

Custom plugins can be added to a {productname} instance by either:

  • Using external_plugins: Use the external_plugins option to specify the URL-based location of the entry point file for the plugin.

  • Copy code into plugins folder: Copy the entry point file (and any other files) into the plugins folder of the distributed {productname} code. The plugin can then be used by including it in the list of plugins specified by the plugins option.

Note
 {companyname} recommends using the external_plugins option for custom plugins.

Example: using external_plugins

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  external_plugins: {
    pluginId: 'https://example.com/customplugincode.min.js'
  },
  plugins: ''
});

Example: copying plugin code into the plugins folder

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'pluginId'
});

Testing {productname}

Due to the range of browser APIs used by {productname}; when testing {productname} or any custom plugins, {productname} requires a testing framework that runs on a real browser. Testing frameworks that mock the browser will not work.

Language localization

If a custom plugin includes any custom UI created using {productname}'s UI APIs, then it may require localization.

{productname} comes with translations for many strings in many languages. To add additional strings to a supported language for a custom plugin, use the following procedure.

  1. Create a “langs” directory in the custom plugin’s root directory for custom translations.

  2. For each language that the plugin supports, create a translation file.

    The files should be JavaScript files and use the relevant language code as the file name. For example: {productname} will search for a Spanish translation file at <your plugin>/langs/es_ES.js, where <your plugin> is to the directory that contains the plugin’s entry point file. For a list of supported languages, see: Supported languages.

  3. In each translation file, add translation strings by passing an object containing key-value pairs of source strings and translation strings to the tinymce.addI18n() API.

  4. In the plugin’s entry point file, call tinymce.PluginManager.requireLangPack() and pass it the plugin identifier and a comma-delimitated string of the language codes to load.

Example: the content of a translation file for additional Spanish translations

tinymce.addI18n('es_ES', {
  'Example plugin': 'Complemento de ejemplo'
});

Example: loading additional translation files for a custom plugin

// Register the custom plugin
tinymce.PluginManager.add('pluginId', (editor, url) => {
  // add plugin code here
});
// Load the required translation files
tinymce.PluginManager.requireLangPack('pluginId', 'es_ES,de_AT');

Example plugin

This example plugin demonstrates how to add a simple toolbar button and menu item. This button opens a dialog that allows a title to be entered into the editor. The menu item will open the same dialog as the button.

liveDemo::custom-plugin[tab="js"]