Module  : Editor Tools
Version : 1.2.3
Author  : Maurice Makaay <maurice@makaay.nl>

This module will add a tool bar to the Phorum message editor, which can be
used by visitors to easily add things like BBcode tags and smileys to
their postings.

This module is mainly a framework, which implements easy to use javascript
functions and a simple API (see below) for adding buttons and help pages
to the tool bar. So on its own, the module does not do much. Other modules
will have to be enabled to add functional buttons to the tool bar. Phorum
is shipped with two modules that can do this: the BBcode and the smileys
module. Please take a look at the settings screens for those modules to
enable the tool bar buttons that you want to use.


Install:
--------

- Unpack the archive and move the directory "editor_tools" to the directory
  "mods" within your Phorum installation (unless this module was packaged
  with your Phorum release);

- Login as administrator in Phorum's administrative interface and
  go to the "Modules" section;

- Enable the module "Editor Tools".

- Enable the "BBcode" and/or "Smileys" module (Editor Tools will
  only show tools for the enabled modules, so if you do not enable
  any of these two, no tools will be displayed at all). Edit the
  settings for the BBcode and Smileys module to configure which
  tool buttons you want to enable.


Language support:
-----------------

This module supports multiple languages. If you want to translate the module
to a new language, you'll have to copy lang/english.php to lang/yourlang.php
(yourlang.php must have the same name as Phorum's main language file that
you use). After this, translate the strings in lang/yourlang.php.

If you have created a translation for this module, please post a copy of
lang/yourlang.php in the module forum at http://www.phorum.org/phorum5, so
we can add the translation to the package.


How to plugin into the editor tools from another module:
--------------------------------------------------------

Other modules can add extra buttons, javascript libraries and help pages to
the editor tools through an easy to use API. See the API functions at the
bottom of editor_tools.php for the full documentation. Here are some quick
examples on how to do this.

1) Create a module. We use "mod_foo" in the examples below.

2) Add an "editor_tool_plugin" hook to the module info, e.g.

   hook: editor_tool_plugin|phorum_mod_foo_editor_tool_plugin

3) Implement the editor_tool_plugin hook function in the module code.
   To add a button, we need to add the javascript for handling a click
   on the editor tool button to the page and register the extra editor
   tool so it will be display. Example code:

      function phorum_mod_foo_editor_tool_plugin()
      {
          global $PHORUM;

          // Add javascript code to handle a click on the tool button.
          // The javascript code is captured and added to the {HEAD_TAGS}
          // template variable, so it will be added to the <head> section
          // of the page through the header.tpl template. Note that you
          // could also use other mechanisms to add the code to the pages,
          // but for small bits of javascript, this might be the easiest
          // way to do it.
          ob_start();
          ?>
          <script type="text/javascript">
            function mod_foo_editor_tool_action() {
              alert('You clicked on the mod_foo editor tool');
            }
          </script>
          <?php
          $PHORUM['DATA']['HEAD_TAGS'] .= ob_get_contents();
          ob_end_clean();

          // Register a tool button.
          editor_tools_register_tool(
              'foo',                         // Tool id
              'Foo module tool',             // Tool description
              './mods/mod_foo/icon.gif',     // Tool button icon
              'mod_foo_editor_tool_action()' // Javascript action on click
              40,                            // Tool icon width
              18                             // Tool icon height
          );

          // Register translation strings. These will be available in the
          // javascript code through the editor_tools_translate() function,
          // e.g. editor_tools_translate('key1') will return 'translation 1'.
          editor_tools_register_translations(array(
              'key1' => 'translation 1',
              'key2' => 'translation 2'
          ));
      }

   Beware that you do not use icons that are higher than 20px. If you do so,
   that might break the layout. Smaller icons are no problem. If you do not
   provide icon width and height, the default values will be used (21px width
   and 20px height).

4) If you want to load a javascript library for your editor tool, you can
   of course add the <script src=...> code from your editor_tool_plugin
   hook directly, but you can also let the editor_tools module handle this
   by using the following call in the hook function:

      editor_tools_register_jslib('relative/path/to/your/library.js');

   Beware that this path is relative to the Phorum installation directory.
   So if you would like to load foo.js from the mod_foo directory, you
   would use the following:

      editor_tools_register_jslib('mods/mod_foo/foo.js');

5) If you want to link a help page to the help button in the editor tools,
   you can add one from the editor_tool_plugin using the following call
   in the hook function:

      editor_tools_register_help(
          'The name of the help link',
          'http://www.yourhelp.com/page.html'
      );


If both mod_foo and the editor_tools module are enabled, the extra
editor tool elements will be available in the button bar.


Color picker information:
-------------------------

For the color picker, we use the excellent script from dhtmlgoodies.com.
The script does need some changes to make it work for the editor tools.
These are the changes that are needed:

1) Delete form{ padding-left:5px; } from the css file.

2) In js_color_picker_v2.js, change all references like 'images/...'
   to '<?php print $GLOBALS["PHORUM"]["http_path"] ?> (continued on next line)
       /mods/editor_tools/colorpicker/images/...'

3) In js_color_picker_v2.js, change the action functions
   chooseColor() and chooseColorSlider() to call the function
   editor_tools_handle_color_select() with the selected color
   as the argument.

4) In js_color_picker_v2.js, add the call
   editor_tools_register_popup_object(color_picker_div);
   after creating the color_picker_div in the function showColorPicker().

5) In the same function, right after the code block for if(!color_picker_div),
   the color picker can be made visible by settings style.display to block.
   Together with that call, the call for closing all popups must be made,
   so change the code to this:
   {editor_tools_hide_all_popups(); color_picker_div.style.display='block';}

6) In the same function, remove the formField argument and also remove the
   line at the end of the function where the formField is stored in a
   global variable.

7) Add z-index: 1000 to the definition for #dhtmlgoodies_colorPicker
   in the css file.

8) Eye candy: change all #317802 in the js_color_picker_v2.css to #777.

9) For MSIE5/MacOS9 support, remove the "?" after the "*" in the line:
   var navigatorVersion = navigator.appVersion.replace(/.*?MSIE...etc)/1;

10) In js_color_picker_v2.css: -moz-user-select:no; -> -moz-user-select:none;
    url('...') -> url(...)

11) In js_color_picker_v2.js.php, for providing more dynamics in the tabs:
    var tabs = ['<?php print $langstr["rgb"] ?>','<?php print $langstr["named"] ?>','<?php print $langstr["slides"] ?>'];
    var tabWidths = [<?php print $langstr["rgb_size"] ?>,<?php print $langstr["named_size"] ?>,<?php print $langstr["slides_size"] ?>];

