Explained how hooks now can get data, documented attachment hook and data

[squirrelmail.git] / doc / plugin.txt

diff --git a/doc/plugin.txt b/doc/plugin.txt
index b9342de1633e3b47f2c9b1d070e8f8bab55265c2..a316b3144fc170c3a27c0eaf43aa0e9a81215a20 100644 (file)
--- a/doc/plugin.txt
+++ b/doc/plugin.txt
@@ -74,44 +74,94 @@ in the plugin directory is requested, it must do a chdir("..") before
 including any of the standard SquirrelMail files.
 
 
 including any of the standard SquirrelMail files.
 
 

+Hook Data Passed
+----------------
+Hooks, when executed, are called with one parameter, an array of data
+that is passed to the hook.  The first element in the array is the name
+of the hook that is being called.  Any other elements in the array are
+dependant on the type of hook that is being called.
+
+Some of the information in the array may be changed.  By default, the
+plugins should never change data unless it is documented otherwise.
+
+

 List of hooks
 -------------
 List of hooks
 -------------

-  generic_header                 functions/page_header.php
-  menuline                       functions/page_header.php
-  compose_button_row             src/compose.php
-  compose_bottom                 src/compose.php
-  left_main_before               src/left_main.php
-  left_main_after                src/left_main.php
-  options_save                   src/options.php  (see note on options)
-  options_link_and_description   src/options.php  (see note on options)
-  options_highlight_bottom       src/options_highlight.php
-  options_personal_bottom        src/options_personal.php
-  options_display_bottom         src/options_display.php
-  options_folders_bottom         src/options_folders.php
-  logout                         src/signout.php
-  login_before                   src/webmail.php
-  login_verified                 src/webmail.php
-  loading_prefs                  src/load_prefs.php
-  mailbox_index_before           functions/mailbox_display.php
-  mailbox_index_after            functions/mailbox_display.php
-  right_main_after_header        src/right_main.php
-  right_main_bottom              src/right_main.php
-  login_top                      src/login.php
-  login_bottom                   src/login.php
-  read_body_top                  src/read_body.php
-  read_body_bottom               src/read_body.php
-  search_before_form             src/search.php
-  search_after_form              src/search.php
-  search_bottom                  src/search.php
-  help_top                       src/help.php
-  help_bottom                    src/help.php
-  help_chapter                   src/help.php
-  abook_html_search_below        src/addrbook_search_html.php
-  addressbook_bottom            src/addressbook.php
+  generic_header                  functions/page_header.php
+  menuline                        functions/page_header.php
+  compose_button_row              src/compose.php
+  compose_bottom                  src/compose.php
+  left_main_before                src/left_main.php
+  left_main_after                 src/left_main.php
+  * options_save                  src/options.php  (see note on options)
+  * options_link_and_description  src/options.php  (see note on options)
+  * options_highlight_bottom      src/options_highlight.php
+  * options_personal_bottom       src/options_personal.php
+  * options_personal_inside       src/options_personal.php
+  * options_personal_save         src/options_personal.php
+  * options_display_bottom        src/options_display.php
+  * options_display_inside        src/options_display.php
+  * options_display_save          src/options_display.php
+  * options_folders_bottom        src/options_folders.php
+  * options_folders_inside        src/options_folders.php
+  * options_folders_save          src/options_folders.php
+  logout                          src/signout.php
+  login_before                    src/webmail.php
+  login_verified                  src/webmail.php
+  loading_prefs                   src/load_prefs.php
+  mailbox_index_before            functions/mailbox_display.php
+  mailbox_index_after             functions/mailbox_display.php
+  mailbox_form_before             functions/mailbox_display.php
+  right_main_after_header         src/right_main.php
+  right_main_bottom               src/right_main.php
+  login_top                       src/login.php
+  login_bottom                    src/login.php
+  read_body_top                   src/read_body.php
+  read_body_bottom                src/read_body.php
+  search_before_form              src/search.php
+  search_after_form               src/search.php
+  search_bottom                   src/search.php
+  help_top                        src/help.php
+  help_bottom                     src/help.php
+  help_chapter                    src/help.php
+  addrbook_html_search_below      src/addrbook_search_html.php
+  addressbook_bottom              src/addressbook.php
+  ^ attachment $type0/$type1      functions/mime.php (see note on attachments)

    
    

-Options
--------
-
+   
+(*) Options
+-----------
+There are two ways to do options for your plugin.  First, you can incorporate it
+into an existing section of the preferences (Display, Personal, or Folders).
+The second way, you create your own section that they can choose from and it 
+displays its own range of options.
+
+
+First:  Integrating into existing options
+-----------------------------------------
+There are two hooks you need to use for this one:
+
+1.  options_YOUCHOOSE_inside
+    This is the code that goes inside the table for the section you choose.  Since
+    it is going inside an existing table, it must be in this form:
+    ------cut here-------
+      <tr>
+         <td>
+            OPTION_NAME
+         </td>
+         <td>
+            OPTION_INPUT
+         </td>
+      </tr>   
+    ------cut here-------
+
+2.  options_YOUCHOOSE_save
+    This is the code that saves your preferences into the users' preference 
+    file.  For an example of how to do this, see src/options.php.
+
+    
+Second:  Create your own section
+-------------------------------

 It is possible to create your own options sections with plugins.  There are
 three hooks you will need to use.
 
 It is possible to create your own options sections with plugins.  There are
 three hooks you will need to use.
 


@@ -153,3 +203,29 @@ three hooks you will need to use.
     You should put the code in here that loads your preferences back
     into usable variables.  Examples of this can be found in the file
     src/load_prefs.php
     You should put the code in here that loads your preferences back
     into usable variables.  Examples of this can be found in the file
     src/load_prefs.php

+
+
+(^) Attachment Hooks
+--------------------
+When a message has attachments, this hook is called with the MIME types.  For
+instance, a .zip file hook is "attachment application/x-zip".  The hook should
+probably show a link to do a specific action, such as "Verify" or "View" for a
+.zip file.
+
+This is a breakdown of the data passed in the array to the hook that is called:
+
+  [0] = Hook's name ('attachment text/plain')
+  [1] = Array of links of actions (more below) (Alterable)
+  [2] = Used for returning to mail message (startMessage)
+  [3] = Used for finding message to display (id)
+  [4] = Mailbox name, urlencode()'d (urlMailbox)
+  [5] = Entity ID inside mail message (ent)
+  [6] = Default URL to go to when filename is clicked on (Alterable)
+  [7] = Sent if message was found from a search (where)
+  [8] = Sent if message was found from a search (what)
+  
+To set up links for actions, you assign them like this:
+  
+  $Args[1]['your_plugin_name']['href'] = 'URL to link to';
+  $Args[1]['your_plugin_name']['text'] = 'What to display';
+    
\ No newline at end of file