Added new scheme to allow multiple plugins to share the onsubmit handler for the...

git-svn-id: https://svn.code.sf.net/p/squirrelmail/code/trunk/squirrelmail@10369 7612ce4b-ef26-0410-bec9-ea0150e637f0

diff --git a/doc/Development/plugin.txt b/doc/Development/plugin.txt
index 6f5c15965eda4fc7819596e87533140c6200615c..01f2755a66f38c1810421835ab0c0f440c5ded42 100644 (file)
--- a/doc/Development/plugin.txt
+++ b/doc/Development/plugin.txt
@@ -303,7 +303,7 @@ but may be out of date soon thereafter.  You never know.  ;-)
   loading_prefs                  include/load_prefs.php          do_hook
   addrbook_html_search_below     src/addrbook_search_html.php    do_hook
   addressbook_bottom             src/addressbook.php             do_hook
-  compose_form                   src/compose.php                 do_hook
+! compose_form                   src/compose.php                 do_hook
   compose_bottom                 src/compose.php                 do_hook
   compose_button_row             src/compose.php                 do_hook
   compose_send                   src/compose.php                 do_hook
@@ -372,6 +372,7 @@ O info_bottom                    plugins/info/options.php        do_hook
 ^ = Special attachments hook (see below)
 * = Special options hooks (see below)
 O = Optional hook provided by a particular plugin
+! = See below for notes about working with the compose page's <form> tag
 
 
 (#) Called With
@@ -382,6 +383,35 @@ Each hook is called using the hook type specified in the list above:
    concat_hook   concat_hook_function()
 
 
+(!) Compose Form
+----------------
+The compose_form hook allows plugins to insert their own code into 
+the form tag for the main message composition HTML form.  Usually
+plugins will want to insert some kind of code in an onsubmit event
+handler.  In order to allow more than one plugin to do so, all plugins
+using this hook to add some onsubmit code need to add that code (without
+the enclosing attribute name and quotes) as a new array entry to the 
+global $compose_onsubmit array.  The code should use "return false"
+if the plugin has found a reason to stop form submission, otherwise,
+it should DO NOTHING (that is, please do not use "return true", as that
+will prevent other plugins from using the onsubmit handler).  SquirrelMail
+itself will insert a final "return true".  All onsubmit code will be
+enclosed in double quotes by SquirrelMail, so plugins need to quote 
+accordingly if needed.  For example:
+
+   global $compose_onsubmit;
+   $compose_onsubmit[] = ' if (somevar == \'no\') return false; ';
+
+Note the escaped single quotes.  If you use double quotes, they would have
+to be escaped as such:
+
+   global $compose_onsubmit;
+   $compose_onsubmit[] = ' if (somevar == \'no\') { alert(\\"Sorry\\"); return false; }';
+
+Any other form tag additions by a plugin (beside onsubmit event code) can 
+currently be echoed directly to the browser.
+
+
 (&) Identity Hooks
 ------------------
 This set of hooks is passed special information in the array of arguments: