* Added the section about validate.php

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

diff --git a/doc/plugin.txt b/doc/plugin.txt
index c3244660b26a2e3f171a7417ff35d835cf018401..f367a97b298c38373db0465e9832ae2cd6f6e777 100644 (file)
--- a/doc/plugin.txt
+++ b/doc/plugin.txt
@@ -173,10 +173,11 @@ three hooks you will need to use.
 
 1.  options_link_and_description
     This creates the link and has a description that are shown on the options
 
 1.  options_link_and_description
     This creates the link and has a description that are shown on the options

-    page.  This should output HTML that looks like this:
+    page.  This should output HTML that looks like this.  Make sure to read
+    the section on outputting your own pages.

 
     -----cut here-----  
 
     -----cut here-----  

-      function my_function() {
+      function my_plugin_name_my_function() {

          global $color
          ?>
          <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>
          global $color
          ?>
          <table width=50% cellpadding=3 cellspacing=0 border=0 align=center>


@@ -236,3 +237,37 @@ 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';
     
   $Args[1]['your_plugin_name']['href'] = 'URL to link to';
   $Args[1]['your_plugin_name']['text'] = 'What to display';
     

+
+Outputting Your Own Pages
+-------------------------
+
+Often, when you want to provide your own customized options screen or create
+another web page instead of just using standard hooks, you will be creating
+your own .php files.  An example of this is the attachment_common plugin's
+image.php file.
+
+To make sure that security is maintained and standards are followed, the top
+of your PHP script should look very similar to this:
+
+  <?PHP
+    /* This is my php file.
+     * description goes here.
+     */
+     
+    chdir('..');
+    include('../src/validate.php');
+    
+The validate.php script will include internationalization support,
+config.php variables, strings.php functions, and also authenticate that the
+user is truly logged in.  Validate.php also calls stripslashes() on incoming
+data (if gpc_magic_quotes() is on).  You should never need to worry about
+that stuff again.  As a warning, this has only really been ironed out in
+1.1.1.  If you create/modify a plugin to follow these rules, you must
+mention that it requires SquirrelMail 1.1.1 or later.
+
+After that, if you need further functions, just use
+
+  include('../functions/filename.php');
+  
+in your script.  Since 1.0.5, it was no longer necessary (nor recommended)
+to use the "if (! isset($filename_php))" syntax.