modules/wysiwyg/wysiwyg.api.php

<?php
// $Id: wysiwyg.api.php,v 1.3 2009/06/09 00:18:11 sun Exp $

/**
 * @file
 * Wysiwyg API documentation.
 *
 * To implement a "Drupal plugin" button, you need to write a Wysiwyg plugin:
 * - Implement hook_wysiwyg_include_directory() to register the directory
 *   containing plugin definitions.
 * - In each plugin definition file, implement hook_INCLUDE_plugin().
 * - For each plugin button, implement a JavaScript integration and an icon for
 *   the button.
 *
 * @todo Icon: Recommended size and type of image.
 *
 * For example implementations you may want to look at
 * - Image Assist (img_assist)
 * - Teaser break plugin (plugins/break; part of WYSIWYG)
 * - IMCE (imce_wysiwyg)
 */

/**
 * Return an array of native editor plugins.
 *
 * Only to be used for native (internal) editor plugins.
 *
 * @see hook_wysiwyg_include_directory()
 *
 * @param $editor
 *   The internal name of the currently processed editor.
 * @param $version
 *   The version of the currently processed editor.
 *
 * @return
 *   An associative array having internal plugin names as keys and an array of
 *   plugin meta-information as values.
 */
function hook_wysiwyg_plugin($editor, $version) {
  switch ($editor) {
    case 'tinymce':
      if ($version > 3) {
        return array(
          'myplugin' => array(
            // A URL to the plugin's homepage.
            'url' => 'http://drupal.org/project/img_assist',
            // The full path to the native editor plugin.
            'path' => drupal_get_path('module', 'img_assist') . '/drupalimage/editor_plugin.js',
            // A list of buttons provided by this native plugin. The key has to
            // match the corresponding JavaScript implementation. The value is
            // is displayed on the editor configuration form only.
            'buttons' => array(
              'img_assist' => t('Image Assist'),
            ),
            // A list of editor extensions provided by this native plugin.
            // Extensions are not displayed as buttons and touch the editor's
            // internals, so you should know what you are doing.
            'extensions' => array(
              'imce' => t('IMCE'),
            ),
            // A list of global, native editor configuration settings to
            // override. To be used rarely and only when required.
            'options' => array(
              'file_browser_callback' => 'imceImageBrowser',
              'inline_styles' => TRUE,
            ),
            // Boolean whether the editor needs to load this plugin. When TRUE,
            // the editor will automatically load the plugin based on the 'path'
            // variable provided. If FALSE, the plugin either does not need to
            // be loaded or is already loaded by something else on the page.
            // Most plugins should define TRUE here.
            'load' => TRUE,
            // Boolean whether this plugin is a native plugin, i.e. shipped with
            // the editor. Definition must be ommitted for plugins provided by
            // other modules.
            'internal' => TRUE,
            // TinyMCE-specific: Additional HTML elements to allow in the markup.
            'extended_valid_elements' => array(
              'img[class|src|border=0|alt|title|width|height|align|name|style]',
            ),
          ),
        );
      }
      break;
  }
}

/**
 * Register a directory containing Wysiwyg plugins.
 *
 * @param $type
 *   The type of objects being collected: either 'plugins' or 'editors'.
 * @return
 *   A sub-directory of the implementing module that contains the corresponding
 *   plugin files. This directory must only contain integration files for
 *   Wysiwyg module.
 */
function hook_wysiwyg_include_directory($type) {
  switch ($type) {
    case 'plugins':
      // You can just return $type, if you place your Wysiwyg plugins into a
      // sub-directory named 'plugins'.
      return $type;
  }
}

/**
 * Define a Wysiwyg plugin.
 *
 * Supposed to be used for "Drupal plugins" (cross-editor plugins) only.
 *
 * @see hook_wysiwyg_plugin()
 *
 * Each plugin file in the specified plugin directory of a module needs to
 * define meta information about the particular plugin provided.
 * The plugin's hook implementation function name is built out of the following:
 * - 'hook': The name of the module providing the plugin.
 * - 'INCLUDE': The basename of the file containing the plugin definition.
 * - 'plugin': Static.
 *
 * For example, if your module's name is 'mymodule' and
 * mymodule_wysiwyg_include_directory() returned 'plugins' as plugin directory,
 * and this directory contains an "awesome" plugin file named 'awesome.inc', i.e.
 *   sites/all/modules/mymodule/plugins/awesome.inc
 * then the corresponding plugin hook function name is:
 *   mymodule_awesome_plugin()
 *
 * @see hook_wysiwyg_include_directory()
 *
 * @return
 *   Meta information about the buttons provided by this plugin.
 */
function hook_INCLUDE_plugin() {
  $plugins['awesome'] = array(
    // The plugin's title; defaulting to its internal name ('awesome').
    'title' => t('Awesome plugin'),
    // The (vendor) homepage of this plugin; defaults to ''.
    'vendor url' => 'http://drupal.org/project/wysiwyg',
    // The path to the button's icon; defaults to
    // '/[path-to-module]/[plugins-directory]/[plugin-name]/images'.
    'icon path' => 'path to icon',
    // The button image filename; defaults to '[plugin-name].png'.
    'icon file' => 'name of the icon file with extension',
    // The button title to display on hover.
    'icon title' => t('Do something'),
    // An alternative path to the integration JavaScript; defaults to
    // '[path-to-module]/[plugins-directory]/[plugin-name]'.
    'js path' => drupal_get_path('module', 'mymodule') . '/awesomeness',
    // An alternative filename of the integration JavaScript; defaults to
    // '[plugin-name].js'.
    'js file' => 'awesome.js',
    // An array of settings for this button. Required, but API is still in flux.
    'settings' => array(
    ),
    // TinyMCE-specific: Additional HTML elements to allow in the markup.
    'extended_valid_elements' => array(
      'tag1[attribute1|attribute2]',
      'tag2[attribute3|attribute4]',
    ),
  );
  return $plugins;
}

1	<?php
2	// $Id: wysiwyg.api.php,v 1.3 2009/06/09 00:18:11 sun Exp $
3
4	/**
5	* @file
6	* Wysiwyg API documentation.
7	*
8	* To implement a "Drupal plugin" button, you need to write a Wysiwyg plugin:
9	* - Implement hook_wysiwyg_include_directory() to register the directory
10	* containing plugin definitions.
11	* - In each plugin definition file, implement hook_INCLUDE_plugin().
12	* - For each plugin button, implement a JavaScript integration and an icon for
13	* the button.
14	*
15	* @todo Icon: Recommended size and type of image.
16	*
17	* For example implementations you may want to look at
18	* - Image Assist (img_assist)
19	* - Teaser break plugin (plugins/break; part of WYSIWYG)
20	* - IMCE (imce_wysiwyg)
21	*/
22
23	/**
24	* Return an array of native editor plugins.
25	*
26	* Only to be used for native (internal) editor plugins.
27	*
28	* @see hook_wysiwyg_include_directory()
29	*
30	* @param $editor
31	* The internal name of the currently processed editor.
32	* @param $version
33	* The version of the currently processed editor.
34	*
35	* @return
36	* An associative array having internal plugin names as keys and an array of
37	* plugin meta-information as values.
38	*/
39	function hook_wysiwyg_plugin($editor, $version) {
40	switch ($editor) {
41	case 'tinymce':
42	if ($version > 3) {
43	return array(
44	'myplugin' => array(
45	// A URL to the plugin's homepage.
46	'url' => 'http://drupal.org/project/img_assist',
47	// The full path to the native editor plugin.
48	'path' => drupal_get_path('module', 'img_assist') . '/drupalimage/editor_plugin.js',
49	// A list of buttons provided by this native plugin. The key has to
50	// match the corresponding JavaScript implementation. The value is
51	// is displayed on the editor configuration form only.
52	'buttons' => array(
53	'img_assist' => t('Image Assist'),
54	),
55	// A list of editor extensions provided by this native plugin.
56	// Extensions are not displayed as buttons and touch the editor's
57	// internals, so you should know what you are doing.
58	'extensions' => array(
59	'imce' => t('IMCE'),
60	),
61	// A list of global, native editor configuration settings to
62	// override. To be used rarely and only when required.
63	'options' => array(
64	'file_browser_callback' => 'imceImageBrowser',
65	'inline_styles' => TRUE,
66	),
67	// Boolean whether the editor needs to load this plugin. When TRUE,
68	// the editor will automatically load the plugin based on the 'path'
69	// variable provided. If FALSE, the plugin either does not need to
70	// be loaded or is already loaded by something else on the page.
71	// Most plugins should define TRUE here.
72	'load' => TRUE,
73	// Boolean whether this plugin is a native plugin, i.e. shipped with
74	// the editor. Definition must be ommitted for plugins provided by
75	// other modules.
76	'internal' => TRUE,
77	// TinyMCE-specific: Additional HTML elements to allow in the markup.
78	'extended_valid_elements' => array(
79	'img[class\|src\|border=0\|alt\|title\|width\|height\|align\|name\|style]',
80	),
81	),
82	);
83	}
84	break;
85	}
86	}
87
88	/**
89	* Register a directory containing Wysiwyg plugins.
90	*
91	* @param $type
92	* The type of objects being collected: either 'plugins' or 'editors'.
93	* @return
94	* A sub-directory of the implementing module that contains the corresponding
95	* plugin files. This directory must only contain integration files for
96	* Wysiwyg module.
97	*/
98	function hook_wysiwyg_include_directory($type) {
99	switch ($type) {
100	case 'plugins':
101	// You can just return $type, if you place your Wysiwyg plugins into a
102	// sub-directory named 'plugins'.
103	return $type;
104	}
105	}
106
107	/**
108	* Define a Wysiwyg plugin.
109	*
110	* Supposed to be used for "Drupal plugins" (cross-editor plugins) only.
111	*
112	* @see hook_wysiwyg_plugin()
113	*
114	* Each plugin file in the specified plugin directory of a module needs to
115	* define meta information about the particular plugin provided.
116	* The plugin's hook implementation function name is built out of the following:
117	* - 'hook': The name of the module providing the plugin.
118	* - 'INCLUDE': The basename of the file containing the plugin definition.
119	* - 'plugin': Static.
120	*
121	* For example, if your module's name is 'mymodule' and
122	* mymodule_wysiwyg_include_directory() returned 'plugins' as plugin directory,
123	* and this directory contains an "awesome" plugin file named 'awesome.inc', i.e.
124	* sites/all/modules/mymodule/plugins/awesome.inc
125	* then the corresponding plugin hook function name is:
126	* mymodule_awesome_plugin()
127	*
128	* @see hook_wysiwyg_include_directory()
129	*
130	* @return
131	* Meta information about the buttons provided by this plugin.
132	*/
133	function hook_INCLUDE_plugin() {
134	$plugins['awesome'] = array(
135	// The plugin's title; defaulting to its internal name ('awesome').
136	'title' => t('Awesome plugin'),
137	// The (vendor) homepage of this plugin; defaults to ''.
138	'vendor url' => 'http://drupal.org/project/wysiwyg',
139	// The path to the button's icon; defaults to
140	// '/[path-to-module]/[plugins-directory]/[plugin-name]/images'.
141	'icon path' => 'path to icon',
142	// The button image filename; defaults to '[plugin-name].png'.
143	'icon file' => 'name of the icon file with extension',
144	// The button title to display on hover.
145	'icon title' => t('Do something'),
146	// An alternative path to the integration JavaScript; defaults to
147	// '[path-to-module]/[plugins-directory]/[plugin-name]'.
148	'js path' => drupal_get_path('module', 'mymodule') . '/awesomeness',
149	// An alternative filename of the integration JavaScript; defaults to
150	// '[plugin-name].js'.
151	'js file' => 'awesome.js',
152	// An array of settings for this button. Required, but API is still in flux.
153	'settings' => array(
154	),
155	// TinyMCE-specific: Additional HTML elements to allow in the markup.
156	'extended_valid_elements' => array(
157	'tag1[attribute1\|attribute2]',
158	'tag2[attribute3\|attribute4]',
159	),
160	);
161	return $plugins;
162	}
163