Issue #1153458 by TwoD: Fixed TinyMCE 'Verify HTML' setting ignored.
[project/wysiwyg.git] / wysiwyg.api.php
1 <?php
2
3 /**
4 * @file
5 * API documentation for Wysiwyg module.
6 *
7 * To implement a "Drupal plugin" button, you need to write a Wysiwyg plugin:
8 * - Implement hook_wysiwyg_include_directory() to register the directory
9 * containing plugin definitions.
10 * - In each plugin definition file, implement hook_INCLUDE_plugin().
11 * - For each plugin button, implement a JavaScript integration and an icon for
12 * the button.
13 *
14 * @todo Icon: Recommended size and type of image.
15 *
16 * For example implementations you may want to look at
17 * - Image Assist (img_assist)
18 * - Teaser break plugin (plugins/break; part of WYSIWYG)
19 * - IMCE (imce_wysiwyg)
20 */
21
22 /**
23 * Return an array of native editor plugins.
24 *
25 * Only to be used for native (internal) editor plugins.
26 *
27 * @see hook_wysiwyg_include_directory()
28 *
29 * @param $editor
30 * The internal name of the currently processed editor.
31 * @param $version
32 * The version of the currently processed editor.
33 *
34 * @return
35 * An associative array having internal plugin names as keys and an array of
36 * plugin meta-information as values.
37 */
38 function hook_wysiwyg_plugin($editor, $version) {
39 switch ($editor) {
40 case 'tinymce':
41 if ($version > 3) {
42 return array(
43 'myplugin' => array(
44 // A URL to the plugin's homepage.
45 'url' => 'http://drupal.org/project/img_assist',
46 // The full path to the native editor plugin, no trailing slash.
47 // Ignored when 'internal' is set to TRUE below.
48 'path' => drupal_get_path('module', 'img_assist') . '/drupalimage',
49 // The name of the plugin's main JavaScript file.
50 // Ignored when 'internal' is set to TRUE below.
51 // Default value depends on which editor the plugin is for.
52 'filename' => 'editor_plugin.js',
53 // A list of buttons provided by this native plugin. The key has to
54 // match the corresponding JavaScript implementation. The value is
55 // is displayed on the editor configuration form only.
56 'buttons' => array(
57 'img_assist' => t('Image Assist'),
58 ),
59 // A list of editor extensions provided by this native plugin.
60 // Extensions are not displayed as buttons and touch the editor's
61 // internals, so you should know what you are doing.
62 'extensions' => array(
63 'imce' => t('IMCE'),
64 ),
65 // A list of global, native editor configuration settings to
66 // override. To be used rarely and only when required.
67 'options' => array(
68 'file_browser_callback' => 'imceImageBrowser',
69 'inline_styles' => TRUE,
70 ),
71 // Boolean whether the editor needs to load this plugin. When TRUE,
72 // the editor will automatically load the plugin based on the 'path'
73 // variable provided. If FALSE, the plugin either does not need to
74 // be loaded or is already loaded by something else on the page.
75 // Most plugins should define TRUE here.
76 'load' => TRUE,
77 // Boolean whether this plugin is a native plugin, i.e. shipped with
78 // the editor. Definition must be ommitted for plugins provided by
79 // other modules. TRUE means 'path' and 'filename' above are ignored
80 // and the plugin is instead loaded from the editor's plugin folder.
81 'internal' => TRUE,
82 // TinyMCE-specific: Additional HTML elements to allow in the markup.
83 'extended_valid_elements' => array(
84 'img[class|src|border=0|alt|title|width|height|align|name|style]',
85 ),
86 ),
87 );
88 }
89 break;
90 }
91 }
92
93 /**
94 * Register a directory containing Wysiwyg plugins.
95 *
96 * @param $type
97 * The type of objects being collected: either 'plugins' or 'editors'.
98 * @return
99 * A sub-directory of the implementing module that contains the corresponding
100 * plugin files. This directory must only contain integration files for
101 * Wysiwyg module.
102 */
103 function hook_wysiwyg_include_directory($type) {
104 switch ($type) {
105 case 'plugins':
106 // You can just return $type, if you place your Wysiwyg plugins into a
107 // sub-directory named 'plugins'.
108 return $type;
109 }
110 }
111
112 /**
113 * Define a Wysiwyg plugin.
114 *
115 * Supposed to be used for "Drupal plugins" (cross-editor plugins) only.
116 *
117 * @see hook_wysiwyg_plugin()
118 *
119 * Each plugin file in the specified plugin directory of a module needs to
120 * define meta information about the particular plugin provided.
121 * The plugin's hook implementation function name is built out of the following:
122 * - 'hook': The name of the module providing the plugin.
123 * - 'INCLUDE': The basename of the file containing the plugin definition.
124 * - 'plugin': Static.
125 *
126 * For example, if your module's name is 'mymodule' and
127 * mymodule_wysiwyg_include_directory() returned 'plugins' as plugin directory,
128 * and this directory contains an "awesome" plugin file named 'awesome.inc', i.e.
129 * sites/all/modules/mymodule/plugins/awesome.inc
130 * then the corresponding plugin hook function name is:
131 * mymodule_awesome_plugin()
132 *
133 * @see hook_wysiwyg_include_directory()
134 *
135 * @return
136 * Meta information about the buttons provided by this plugin.
137 */
138 function hook_INCLUDE_plugin() {
139 $plugins['awesome'] = array(
140 // The plugin's title; defaulting to its internal name ('awesome').
141 'title' => t('Awesome plugin'),
142 // The (vendor) homepage of this plugin; defaults to ''.
143 'vendor url' => 'http://drupal.org/project/wysiwyg',
144 // The path to the button's icon; defaults to
145 // '/[path-to-module]/[plugins-directory]/[plugin-name]/images'.
146 'icon path' => 'path to icon',
147 // The button image filename; defaults to '[plugin-name].png'.
148 'icon file' => 'name of the icon file with extension',
149 // The button title to display on hover.
150 'icon title' => t('Do something'),
151 // An alternative path to the integration JavaScript; defaults to
152 // '[path-to-module]/[plugins-directory]/[plugin-name]'.
153 'js path' => drupal_get_path('module', 'mymodule') . '/awesomeness',
154 // An alternative filename of the integration JavaScript; defaults to
155 // '[plugin-name].js'.
156 'js file' => 'awesome.js',
157 // An alternative path to the integration stylesheet; defaults to
158 // '[path-to-module]/[plugins-directory]/[plugin-name]'.
159 'css path' => drupal_get_path('module', 'mymodule') . '/awesomeness',
160 // An alternative filename of the integration stylesheet; defaults to
161 // '[plugin-name].css'.
162 'css file' => 'awesome.css',
163 // An array of settings for this button. Required, but API is still in flux.
164 'settings' => array(
165 ),
166 // TinyMCE-specific: Additional HTML elements to allow in the markup.
167 'extended_valid_elements' => array(
168 'tag1[attribute1|attribute2]',
169 'tag2[attribute3|attribute4]',
170 ),
171 );
172 return $plugins;
173 }
174
175 /**
176 * Act on editor profile settings.
177 *
178 * This hook is invoked from wysiwyg_get_editor_config() after the JavaScript
179 * settings have been generated for an editor profile and before the settings
180 * are added to the page. The settings may be customized or enhanced; typically
181 * with options that cannot be controlled through Wysiwyg module's
182 * administrative UI currently.
183 *
184 * Modules implementing this hook to enforce settings that can also be
185 * controlled through the UI should also implement
186 * hook_form_wysiwyg_profile_form_alter() to adjust or at least indicate on the
187 * editor profile configuration form that certain/affected settings cannot be
188 * changed.
189 *
190 * @param $settings
191 * An associative array of JavaScript settings to pass to the editor.
192 * @param $context
193 * An associative array containing additional context information:
194 * - editor: The plugin definition array of the editor.
195 * - profile: The editor profile object, as loaded from the database.
196 * - theme: The name of the editor theme/skin.
197 */
198 function hook_wysiwyg_editor_settings_alter(&$settings, $context) {
199 // Each editor has its own collection of native settings that may be extended
200 // or overridden. Please consult the respective official vendor documentation
201 // for details.
202 if ($context['profile']->editor == 'tinymce') {
203 // Supported values to JSON data types.
204 $settings['cleanup_on_startup'] = TRUE;
205 }
206 }