Issue backdrop#101 by quicksketch, Wim Leers, Reinmar, jessebeach, no…

…d_, sun, effulgentsia: Initial version of the CKEditor module, mix of ported D8 code and wysiwyg_ckeditor.module code.

core/modules/ckeditor5/core/modules/ckeditor/ckeditor.admin.inc

@@ -0,0 +1,122 @@
+<?php
+/**
+ * Admin menu callbacks and theme functions for CKEditor module.
+ */
+
+/**
+ * Editor settings callback; Provide options for CKEditor module.
+ */
+function ckeditor_settings_form(&$form, $form_state, $format) {
+  $plugins = ckeditor_plugins();
+  $toolbar_element = theme('ckeditor_settings_toolbar', array('format' => $format, 'plugins' => $plugins));
+  $elements = array(
+    '#attached' => array(
+      'library' => array(
+        array('ckeditor', 'backdrop.ckeditor.admin'),
+      ),
+      'js' => array(
+        array('data' => array('ckeditor' => array('toolbarAdmin' => $toolbar_element)), 'type' => 'setting')
+      ),
+    ),
+    '#attributes' => array('class' => array('ckeditor-toolbar-configuration')),
+  );
+  $elements['toolbar'] = array(
+    '#type' => 'textarea',
+    '#title' => t('Toolbar configuration'),
+    '#default_value' => json_encode($format->editor_settings['toolbar']),
+    '#attributes' => array('class' => array('ckeditor-toolbar-textarea')),
+  );
+
+  // @todo: Have this settings form be provided via a plugin hook.
+  $elements['plugins']['style']['style_list'] = array(
+    '#title' => t('CKEditor style list'),
+    '#type' => 'textarea',
+    '#rows' => 4,
+    '#default_value' => _ckeditor_settings_stringify_style_list($format->editor_settings['plugins']['style']['style_list']),
+    '#description' => t('A list of classes that will be provided in the "Styles" dropdown. Enter one class on each line in the format: element.class|Label. Example: h1.title|Title.') . '<br />' . t('Each style should be in your theme\'s main CSS as well as in your theme\'s ckeditor-iframe.css file.'),
+  );
+
+  array_unshift($form['#validate'], 'ckeditor_settings_form_validate');
+  array_unshift($form['#submit'], 'ckeditor_settings_form_submit');
+  return $elements;
+}
+
+/**
+ * Additional validate handler for filter_admin_format_form().
+ */
+function ckeditor_settings_form_validate($form, &$form_state) {
+  $settings = $form_state['values']['editor_settings'];
+  $toolbar_string = $settings['toolbar'];
+  $result = json_decode($toolbar_string, TRUE);
+  if (empty($result)) {
+    form_error($form['editor_settings']['toolbar'], t('The CKEditor toolbar configuration could not be saved.'));
+  }
+
+  $styles = _ckeditor_settings_parse_style_list($settings['plugins']['style']['style_list']);
+  foreach ($styles as $style) {
+    if (empty($style['name']) || empty($style['element']) || empty($style['attributes']['class'])) {
+      form_error($form['editor_settings']['plugins']['style']['style_list'], t('The CKEditor list of styles is not formatted properly. Be sure to include one style per line, with the format "element.class|Label".'));
+    }
+  }
+}
+
+/**
+ * Additional submit handler for filter_admin_format_form().
+ */
+function ckeditor_settings_form_submit($form, &$form_state) {
+  $settings = $form_state['values']['editor_settings'];
+  form_set_value($form['editor_settings']['toolbar'], json_decode($settings['toolbar'], TRUE), $form_state);
+
+  $styles = _ckeditor_settings_parse_style_list($settings['plugins']['style']['style_list']);
+  form_set_value($form['editor_settings']['plugins']['style']['style_list'], $styles, $form_state);
+}
+
+/**
+ * Parse a string of styles in the format of element.class|Label into an array.
+ *
+ * @param string $style_list_string
+ *   A list of styles separated by new line characters.
+ *
+ * @return array
+ *   An unindexed array of styles with the following keys:
+ *   - name: The label of the style.
+ *   - element: The type of element this still will use.
+ *   - attributes: An attributes array including the class that will be used.
+ *     Note that the class is not an array, as this configuration is passed
+ *     directly to CKEditor.
+ */
+function _ckeditor_settings_parse_style_list($style_list_string) {
+  $styles = array();
+  foreach (explode("\n", $style_list_string) as $style) {
+    $style = trim($style);
+    if ($style) {
+      @list($element, $label) = explode('|', $style, 2);
+      @list($element, $class) = explode('.', $element, 2);
+      $styles[] = array(
+        'name' => $label,
+        'element' => $element,
+        'attributes' => array('class' => $class),
+      );
+    }
+  }
+  return $styles;
+}
+
+/**
+ * Convert the stored array of styles into a string for editing.
+ *
+ * @param array $style_list
+ *   The style list as returned by _ckeditor_settings_parse_style_list().
+ *
+ * @return string
+ *   The string representation of the style list.
+ */
+function _ckeditor_settings_stringify_style_list(array $style_list = NULL) {
+  $string = '';
+  if ($style_list) {
+    foreach ($style_list as $style) {
+      $string .= $style['element'] . '.' . $style['attributes']['class'] . '|' . $style['name'] . "\n";
+    }
+  }
+  return $string;
+}

core/modules/ckeditor5/core/modules/ckeditor/ckeditor.api.php

@@ -0,0 +1,155 @@
+<?php
+
+/**
+ * @file
+ * Documentation for CKEditor module APIs.
+ */
+
+/**
+ * @addtogroup hooks
+ * @{
+ */
+
+/**
+ * Provides a list of CKEditor 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:
+ *
+ * - location: 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 "location" 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 "location" 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 to be allowed,
+ *     specify an array of tags.
+ * @return array
+ *   An array of plugin definitions, keyed by the plugin name.
+ *
+ * @see ckeditor_ckeditor_plugins()
+ * @see hook_ckeditor_PLUGIN_plugin_check()
+ */
+function hook_ckeditor_plugins() {
+  $plugins['myplugin'] = array(
+    'path' => backdrop_get_path('module', 'mymodule') . '/js/myplugin',
+    'file' => 'plugin.js',
+    'css' => array(backdrop_get_path('module', 'mymodule') . '/css/myplugin.css'),
+    'enabled callback' => 'mymodule_myplugin_plugin_check',
+  );
+
+  return $plugins;
+}
+
+/**
+ * Modify the list of available CKEditor plugins.
+ *
+ * This hook may be used to modify plugin properties after they have been
+ * specified by other modules.
+ *
+ * @param $plugins
+ *   An array of all the existing plugin definitions, passed by reference.
+ *
+ * @see hook_ckeditor_plugins()
+ */
+function hook_ckeditor_plugins_alter(array &$plugins) {
+  $plugins['someplugin']['enabled callback'] = 'mymodule_someplugin_enabled_callback';
+}
+
+/**
+ * Modify the list of CSS files that will be added to a CKEditor instance.
+ *
+ * Modules may use this hook to provide their own custom CSS file without
+ * providing a CKEditor plugin. This list of CSS files is only used in the
+ * iframe versions of CKEditor.
+ *
+ * Note that because this hook is only called for modules and the active theme,
+ * front-end themes will not be able to use this hook to add their own CSS files
+ * if a different admin theme is active. Instead, front-end themes and base
+ * themes may specify CSS files to be used in iframe instances of CKEditor
+ * through an entry in their .info file:
+ *
+ * @code
+ * ckeditor_stylesheets[] = css/ckeditor-iframe.css
+ * @endcode
+ *
+ * @param $css
+ *   An array of CSS files, passed by reference. This is a flat list of file
+ *   paths relative to the Backdrop root.
+ * @param $editor
+ *   The editor object as returned by editor_load(), for which these files are
+ *   being loaded.
+ * @param $format
+ *   The corresponding text format object as returned by filter_format_load()
+ *   for which the current text editor is being displayed.
+ *
+ * @see _ckeditor_theme_css()
+ */
+function hook_ckeditor_css_alter(array &$css, $editor, $format) {
+  $css[] = backdrop_get_path('module', 'mymodule') . '/css/mymodule-ckeditor.css';
+}
+
+/**
+ * @} End of "addtogroup hooks".
+ */
+
+/**
+ * Enabled callback for hook_ckeditor_plugins().
+ *
+ * Note: This is not really a hook. The function name is manually specified via
+ * 'enabled callback' in hook_ckeditor_plugins(), with this recommended callback
+ * name pattern. It is called from ckeditor_add_settings().
+ *
+ * This callback should determine if a plugin should be enabled for a CKEditor
+ * instance. Plugins may be enabled based off an explicit setting, or enable
+ * themselves based on the configuration of another setting, such as enabling
+ * based on a particular button being present in the toolbar.
+ *
+ * @param object $format
+ *   An format object as returned by filter_format_load(). The editor's settings
+ *   may be found in $format->editor_settings.
+ * @param string $plugin_name
+ *   String name of the plugin that is being checked.
+ *
+ * @return boolean
+ *   Boolean TRUE if the plugin should be enabled, FALSE otherwise.
+ *
+ * @see hook_ckeditor_plugins()
+ * @see ckeditor_add_settings()
+ */
+function hook_ckeditor_PLUGIN_plugin_check($format, $plugin_name) {
+  // Automatically enable this plugin if the Underline button is enabled.
+  foreach ($format->editor_settings['toolbar']['buttons'] as $row) {
+    if (in_array('Underline', $row)) {
+      return TRUE;
+    }
+  }
+}

core/modules/ckeditor5/core/modules/ckeditor/ckeditor.info

@@ -0,0 +1,4 @@
+name = CKEditor
+description = WYSIWYG editing for rich text fields using CKEditor.
+package = User interface
+backdrop = 1.x