1 ckeditor.api.php hook_ckeditor_plugins()

Provides a list of CKEditor 4 plugins.

Each plugin for CKEditor must provide an array of properties containing information about the plugin. At minimum, plugins must provide a path and file location so that CKEditor may add the plugin. Available properties for each plugin include:

  • path: Required for all external plugins. String path to the plugin directory relative to the Backdrop installation root. Do not include a trailing slash.
  • file: Required for all external plugins. String file name of the plugin in the "path" directory.
  • internal: Boolean value indicating if the plugin is part of the compressed CKEditor library package and already loaded on all instances. If TRUE, the "path" and "file" properties are not needed.
  • css: An array of CSS files that should be added by CKEditor. These files are used only when CKEditor is using an iframe wrapper around its content. If a plugin needs to include CSS for inline and iframe versions, it should add its CSS via CKEditor's JavaScript CKEDITOR.addCss() method.
  • enabled callback: String containing a function name that can determine if this plugin should be enabled based on the current editor configuration. See the hook_ckeditor_PLUGIN_plugin_check() function for an example.
  • buttons: An array of buttons that are provided by this plugin. Each button should by keyed by its CKEditor button name, and should contain an array of button properties, including:

    • label: A human-readable, translated button name.
    • image: An image for the button to be used in the toolbar.
    • image_rtl: If the image needs to have a right-to-left version, specify an alternative file that will be used in RTL editors.
    • image_alternative: If this button does not render as an image, specify an HTML string representing the contents of this button. This alternative will only be used in the administrative section for assembling the toolbar.
    • attributes: An array of HTML attributes which should be added to this button when rendering the button in the administrative section for assembling the toolbar.
    • multiple: Boolean value indicating if this button may be added multiple times to the toolbar. This typically is only applicable for dividers and group indicators.
    • required_html: If this button requires certain HTML tags or attributes to be allowed, specify an nested array for each set of tags that should be allowed. For example: 
    array(
      array(
        'tags' => array('a'),
        'attributes' => array('href', 'alt'),
        'styles' => array('color', 'text-decoration'),
        'classes' => array('external', 'internal'),
      ),
    );

Note that this must be a nested array, to allow for the button to require different attributes on different tags.

  • dependencies: An array of other plugin names on which this button depends. A common use is to add the "contextmenu" plugin, if the button makes options available only via contextual menu.
  • optional_html: If this button can work with or without certain tags or attributes in a reduced manner, then specify additional values that can be used to provide the full functionality. This should match the same format as the "required_html" return value.

Return value

array: An array of plugin definitions, keyed by the plugin name.

See also

ckeditor_ckeditor_plugins()

hook_ckeditor_PLUGIN_plugin_check()

Related topics

Hooks Allow modules to interact with the Backdrop core.

File

core/modules/ckeditor/ckeditor.api.php, line 81
Documentation for CKEditor 4 module APIs.

Code

function hook_ckeditor_plugins() {
  $plugins['myplugin'] = array(
    'path' => backdrop_get_path('module', 'my_module') . '/js/myplugin',
    'file' => 'plugin.js',
    'css' => array(backdrop_get_path('module', 'my_module') . '/css/myplugin.css'),
    'enabled callback' => 'my_module_myplugin_plugin_check',
    'buttons' => array(
      'MyPlugin' => array(
        'label' => t('My custom button'),
        'required_html' => array(
          'tags' => array('a'),
          'attributes' => array('href', 'alt'),
          'styles' => array('color', 'text-decoration'),
          'classes' => array('external', 'internal'),
        ),
        'dependencies' => array('contextmenu'),
      ),
    ),
  );

  return $plugins;
}