Change record status: 
Project: 
Introduced in branch: 
6.x-2.x
Introduced in version: 
6.x-2.5
Description: 

Wysiwyg module passes the editor settings structure generated on the server to the client as a JSON-encoded string.
JSON structures can not contain some of the JavaScript datatypes need by several editor libraries, such as Function references (often used for callbacks) or Regular Expressions.

To work around this Wysiwyg's clientside will scan through the settings structure before passing it to the editor library and identify any JavaScript Objects which have a drupalWysiwygType property with a value of either 'callback' or 'regexp'. These Objects will be replaced by an actual Function reference or RegExp object respectively, allowing more complex settings to be configured on the server.

There is currently no way to use these settings type via the editor profile GUI, but they can be added by implementing hooks such as hook_wysiwyg_editor_settings_alter(). There are two helper functions for creating the proper structures; wysiwyg_wrap_js_callback($name, $context) and wysiwyg_wrap_js_regexp($regexp, $modifiers).

Example for configuring CKEditor 4's protectedSource setting using RegExp objects:


/**
 * Implements hook_wysiwyg_editor_settings_alter().
 */
function MYMODULE_wysiwyg_editor_settings_alter(&$settings, $context) {
  if ($context['profile']->editor == 'ckeditor') {
    $settings['protectedSources'] = array(
      wysiwyg_wrap_js_regexp('<%[\s\S]*?%>', 'g'), // ASP code
      wysiwyg_wrap_js_regexp('<%[\s\S]*?%>', 'g'), // ASP code
    );
  }
}

Example for configuring CKEditor 4's devtools_textCallback settings using a callback.
Note the second parameter to the helper function, which denotes the globally accessible Object which the callback is located in.
It is strongly advised to not put callbacks in the global namespace, but it is possible to reference them by leaving out the second parameter. (Wysiwyg uses the window object to access Functions in the global namespace.)


/**
 * Implements hook_wysiwyg_editor_settings_alter().
 */
function MYMODULE_wysiwyg_editor_settings_alter(&$settings, $context) {
  if ($context['profile']->editor == 'ckeditor') {
    // Function code cannot be inlined, place it in a separate file and add it to the page.
    $settings['devtools_textCallback'] = wysiwyg_wrap_js_callback('myCallback', 'Drupal.MYMODULE');
    drupal_add_js(drupal_get_path('module', 'MYMODULE') . '/js/myfile.js');
  }
}

Since the actual function code can not be inlined, it must be loaded using a separate file. (The callback here is from the CKEditor documentation.)
MYMODULE/js/myfile.js:

Drupal.MYMODULE.myCallback = function( editor, dialog, element, tabName ) {
    var lang = editor.lang.devtools,
        link = '<a href="http://docs.ckeditor.com/#!/api/CKEDITOR.dialog.definition.' +
            ( element ? ( element.type == 'text' ? 'textInput' : element.type ) : 'content' ) +
            '.html" target="_blank">' + ( element ? element.type : 'content' ) + '</a>',
        str =
            '<h2>' + lang.title + '</h2>' +
            '<ul>' +
                '<li><strong>' + lang.dialogName + '</strong> : ' + dialog.getName() + '</li>' +
                '<li><strong>' + lang.tabName + '</strong> : ' + tabName + '</li>';

    if ( element )
        str += '<li><strong>' + lang.elementId + '</strong> : ' + element.id + '</li>';

    str += '<li><strong>' + lang.elementType + '</strong> : ' + link + '</li>';

    return str + '</ul>';
};

The main documentation for the helper functions can be found in wysiwyg.module and they are considered part of the public API.

Impacts: 
Site builders, administrators, editors
Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done