Index: wysiwyg.api.php
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/wysiwyg/wysiwyg.api.php,v
retrieving revision 1.2
diff -u -r1.2 wysiwyg.api.php
--- wysiwyg.api.php	29 Oct 2008 12:20:20 -0000	1.2
+++ wysiwyg.api.php	11 Feb 2009 16:57:50 -0000
@@ -63,3 +63,90 @@
   }
 }
 
+/**
+ * 2. Module developers: How to add a button to the WYSIWYG editors.
+ *
+ * WYSIWYG API supports two types: Editors (see above) and plugins. To include an editor
+ * button we need to write a WYSIWYG plugin.
+ * Three steps are required to register a plugin:
+ *      a) Register the directory for the plugin file: hook_wysiwyg_include_directory().
+ *      b) Create the plugin directory and register the plugin: hook_wysiwyg_plugin().
+ *      c) Create javascript, css and an icon for the button.
+ * For examples refer to the plugin of img_assist or break (part of WYSIWYG).
+ */
+
+/**
+ * 2.a) Register the directory for the plugin file: hook_wysiwyg_include_directory().
+ *
+ * In your .module file include the function below, e.g. for your_module it would be
+ * your_module_wysiwyg_include_directory($type).
+ *
+ * @param string $type
+ *   Contains either "plugins" or "editors"?
+ * @return string
+ *   The function returns the include directory "plugins". This directory must only
+ *   contain wysiwyg api integration files.
+ */
+function hook_wysiwyg_include_directory($type) {
+  switch ($type) {
+    case 'plugins':
+      return $type;
+  }
+}
+
+/**
+ * 2.b) Create the plugin directory and register the plugin: hook_wysiwyg_plugin().
+ *
+ * In your module folder create the directory "plugins" and an include file. The name
+ * of the plugin is defined by the filename of the include file. This name can be
+ * arbitrary. However, the basename of the filename has an influence on the very first
+ * registry function in the .inc file.
+ *
+ * This registry function setups the button. Its name must include the name of your
+ * module (the module that contains hook_wysiwyg_include_directory of step (a)) and
+ * the name of the plugin, e.g. your_module_your_plugin_plugin().
+ *
+ * @return array
+ *   Contains the parameters for the button. The keys are quite self-explanatory.
+ *   The most parameters have a default value and are optional, i.e. you do not need
+ *   to include each listed key into your array.
+ */
+function hook_wysiwyg_plugin() {
+  $plugins = array();
+  $plugins['name_of_plugin'] = array(
+    'title' => t('Title of the Plugin'),                                // Optional, default plugin name.
+    'vendor url' => 'http://drupal.org/project/your_module',            // Recommended, default ''.
+    'js path' => 'path to the javascript file for button functions',    // Optional, default [path-to-module]/[plugin directory]/[plugin name].
+    'js file' => 'name of javascript file with extension',              // Optional, default [plugin name].js.
+    'css path' => 'path of the stylesheet file',                        // Optional, default [path-to-module]/[plugin directory]/[plugin name].
+    'css file' => 'name of stylesheet file with extension',             // Optional, default [plugin name].css.
+    'icon path' => 'path to icon',                                      // Optional, default [path-to-module]/[plugin directory]/[plugin name]/images.
+    'icon file' => 'name of the icon file with extension',              // Optional, default [plugin name].png.
+    'icon title' => t('What this button does'),                         // Required.
+    'dialog path' => 'What is this for?',                               // Optional, default [plugin name]. What is meant by dialog? A different dialog than the one which is set in 'settings'?
+    'dialog settings' => array(),                                       // Optional. See question above.
+    'settings callback' => NULL,                                        // Optional. I can define a custom form function for the dialog in question?
+    'settings form callback' => NULL,                                   // Optional. See question above.
+    'settings' => array(                                                // Required. Array that set the onclick event for the button?
+      'path' => 'What is this for?',                                    // Optional, default [path-to-module]/[plugin directory]/[plugin name].
+      'dialog' => array(                                                // Type of action. Other types than 'dialog' possible?
+        'url' => base_path() . 'url of the popup window',               // Required for 'dialog'.
+        'width' => 200,                                                 // Required for 'dialog'.
+        'height' => 200,                                                // Required for 'dialog'.
+      ),
+    ),
+    // Optional, extend the valid elements for the default HTML filter module?
+    'extended_valid_elements' => array('tag1[attribute1|attribute2]','tag2[attribute1|attribute2]'),
+  );
+  return $plugins;
+}
+
+/**
+ * 2.c) Create javascript, css and icon for the button.
+ *
+ * After the pathes and files have been set in (b) we actually need to create those pathes and files.
+ *
+ * @todo: Javascript: Explain Drupal.wysiwyg.plugins object containing isNode, invoke, attach, detach, _getPlaceholder.
+ * @todo: Stylesheet: Explain function of styles for plugins.
+ * @todo: Icon: Recommended size and type of image.
+ */