wysiwyg.api.php 8.2 KB

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